第 1 章资产创建

配置好协作基础设施，让成员能顺畅完成"新建分支 → 提 PR → 审查 → 合入"。

1.1 仓库初始化

创建仓库，添加 README、LICENSE（如适用）、.gitignore。
将 main 设为默认长期分支。
内部项目与练手项目均托管于实验室 Gitea（《用户层手册》第 0 章明确不使用 GitHub）。

课题组以 C++ 和 MATLAB 为主，.gitignore 建仓时即写入以下常见忽略项，从源头避免误提交编译产物与大文件：

# 编译产物 / 构建目录
build/
bin/
*.o
*.obj
*.exe
*.dll
*.lib
*.a
*.so
*.out

# MATLAB
*.asv
*.mex*
slprj/
*.autosave

# 数据与模型（不纳入版本控制，仅在 PR 说明来源）
*.mat
*.dat
*.bin
*.csv
data/
datasets/

# IDE / 编辑器
.vs/
.vscode/
.idea/
*.user

# 系统与临时文件
Thumbs.db
.DS_Store
*.log
*.tmp

# 密钥 / 环境变量
.env
*.key
*.pem

数据、模型等大文件不进仓库的完整规则与例外评估流程见《用户层手册》第 5.2 节。如某项目确需纳管 *.csv、*.mat 等，可在该项目 .gitignore 中按需放开。

1.1.1 统一换行符（.gitattributes）

实验室以 Windows 为主，不同成员的编辑器与 core.autocrlf 设置不一，易产生"整文件被改"的假 diff 与满屏换行差异。建仓时即提交一个 .gitattributes，从源头统一换行策略，成员无需各自配置：

# 默认按文本处理，仓库内统一存为 LF
* text=auto eol=lf

# 明确指定二进制类型，避免被当文本改写
*.png binary
*.jpg binary
*.pdf binary
*.mat binary
*.bin binary
*.exe binary

.gitattributes 随仓库分发、对所有成员生效，优先级高于个人的 core.autocrlf。成员不要再手动改 core.autocrlf，一切以仓库策略为准。

1.2 分支保护（关键）

在平台上把 main 设为受保护分支：

禁止直接推送，所有成员经 PR。
禁止强制推送。
要求 PR 审核通过才可合并。
仅维护者拥有合并权限。

Gitea 具体操作路径：

仓库 -> Settings -> Branches -> Branch Protection -> Add Rule

在规则中按下表勾选：

选项	设置	对应要求
Protected Branch Name	`main`	保护主线
Enable Push	关闭（或仅限维护者）	禁止直推
Enable Force Push	关闭	禁止强推
Enable Merge Whitelist	开启，仅勾选维护者	仅维护者可合并
Require approvals	设为 `1`（或按需更多）	需审核通过才可合并
Dismiss stale approvals	开启	有新提交后旧的批准失效，须复审

1.2.1 成员与角色权限映射

在 Gitea 按「组织 / 仓库 -> Settings -> Collaborators / Teams」添加成员，将手册角色映射到 Gitea 权限级别：

手册角色	Gitea 权限级别	能做什么
报告人（Reporter）	Read	克隆、看代码、提 Issue、评论
开发者（Developer）	Write	推送到功能分支、提 PR（受分支保护限制无法直推 `main`）
维护者（Maintainer）	Write + 合并白名单	在 Write 基础上，加入 `main` 的 Merge Whitelist，拥有合并与签字权
管理员（Administrator）	Admin / Owner	仓库设置、分支保护、成员管理、破坏性操作（见第 3 章）

组织内推荐用 Team 批量授权：建 developers、maintainers 两个 Team，成员加入对应 Team 即继承权限，避免逐仓库逐人配置。

1.3 模板预置

PR / Issue 模板：置于 .github/（GitHub）或 .gitea/（Gitea），平台自动渲染。练手项目已内置 wip / bug / feature / experiment / docs 模板。
共享模板库：templates/ 存放 commit body 四段、实验记录、成员卡片等模板。

1.4 自动化检查（暂缓）

当前阶段以人工 Review 为主，暂不接入 CI 流水线；提 PR 后由维护者按第 2 章六维审查把关。
需要时成员在本地手动跑检查脚本（如练手项目的 scripts/check-members.py）自测，结果写入 PR。
待协作量上升、团队熟悉流程后，再接入自动化流水线（Gitea Actions / GitHub Actions），届时严格度先设为非阻塞（warn）。

1.5 scope 列表维护

在 README 维护本项目 scope 清单（模块名及含义），供开发者对照填写。
出现新模块及时补充。

1.6 检查清单

项	完成标准
仓库 + main 默认分支	已创建
分支保护	禁止直推 / 禁止强推 / 需审核 / 仅维护者合入
PR / Issue 模板	已预置并可用
scope 列表	README 已维护

练手项目已完成上述配置，可对照 lab-git-practice 的 .github/ 与 templates/ 目录。

第 1 章 资产创建