# 03 — Git 工作流 小团队,流程从轻。分支、commit、PR、review、tag。 ## 分支 - `main` 永远可发。不直接 push,没有例外。 - 功能分支:`/` —— 比如 `bai/auth-retry`、 `bai/eval-agent-rerun`。小写、连字符、你的 handle 做前缀。 - 长期集成分支:`integration/` —— 团队同意才用。 - 合并完删分支。老分支会污染搜索结果。 ## Commit 格式: ``` : <祈使句小结,60 字符以内> <可选 body —— 写改了什么、为什么,不写怎么改> ``` - `` 是目录或组件,小写:`eval-agent`、`task_assistant`、 `docs`、`git-workflow`。 - 祈使句:`add`、`fix`、`rename`,不要 `added` / `adding`。 - Body 在 ~72 字符换行。普通改动跳过 body。 - 一个 commit 一个主题。摘要里出现"and"——拆。 - AI 协作的 commit 保留 Claude Code 默认加的 `Co-Authored-By` trailer。 别去掉。 - Commit message 用英文(vibe coding 守则之一:给 AI 看的内容用英文)。 例: ``` eval-agent: rerun failed tasks with stable seed docs: clarify branch naming in git-workflow task_assistant: drop unused legacy export path ``` ## Pull Request - 一个 PR 一个主题。一句话说不清楚——拆成多个 PR。 - 标题 70 字符以内,跟 commit 摘要同一形态。 - Description 用 `templates/PR_DESCRIPTION.template.md`。 - 第一次 push feature 分支用 `-u`,让它跟踪远端。 - 有可跑的东西就开 PR,draft 也行。边写边 review 比写完再 review 好。 ## Review 每个 PR 都要 review,包括 AI 协作出的,自己也不能跳。 Reviewer 检查清单: 1. Description 跟 diff 对得上吗?diff 有惊喜——发问。 2. 改的每个文件都看一遍。文件跟主题无关——发问为什么进了 PR。 3. 改动不是显而易见就本地跑一遍。 4. 新依赖、schema 变更、env var、动 auth 的代码——讲清楚理由前 block。 5. 评论先发**最不重要**的;merge-blocker 留到最后,让它明显是闸门。 作者收尾: - 每条评论都回应,哪怕只是"同意,已在 修"。 - 不同意写出来 push back,不要默默忽略。 - 合并前把噪音 commit 压一下(squash fixup commits)。 ## 合并 - Feature 分支用 squash。Merge commit 留给集成分支。 - 最终 squash message 按 commit 格式写。PR 标题通常就是好起点。 - 合并完删分支。 ## Tag(版本管理) 按日期打 tag:`YYYYMMDD`(比如 `20260520`)。每个 tag 是 `main` 某一时刻的快照——值得指着说"我们就按这版来"。 规则: - 只在 `main` 上打 tag。功能分支打 tag 是 smell。 - 一天最多一个 tag。同一天再切一个,加 `-N` 后缀:`20260520-2`、 `20260520-3`。 - 用 annotated tag,不用 lightweight。`git tag -a` 加一两句说自上次 tag 以来改了什么。 - Tag 一旦推到远端就不能改、不能删、不能 force-tag。错了就再切一个。 - Tag commit、push tag、告诉大家 tag 名字——这就是发布。 切 tag: ```bash git checkout main git pull --ff-only git tag -a 20260520 -m "team-guide 20260520: bilingual README, dated tags" git push origin 20260520 ``` 查看 / 对比: ```bash git tag --sort=-creatordate # 按时间倒序 git show 20260520 # 看一个 tag 里有什么 git log --oneline 20260513..20260520 # 两个 tag 之间改了什么 ``` 什么时候切 tag: - 本仓库的 docs 改了,队友需要重新读。 - 加了、删了或重组了 template。 - 新的约定正式生效(不是还在讨论)。 什么时候**不**切 tag: - 改错别字、调格式、修死链 → 直接 push 到 `main`。 - 还在讨论的草稿 → 走 PR,不打 tag。 ## 不要做的事 - 不要 `git push --force` 到 `main`。永远不要。push 到自己分支 也只在确定没人 pull 过的情况下。 - 不要 `--no-verify` 跳 hook。修 hook 报的问题。 - 不要 amend 已经 push 的 commit。已经在远端的就加新 commit。 - 不要删或移已经 push 的 tag。错了就切新的。 - 不要提交 `.env`、密钥、或者 ~5 MB 以上的文件——大文件先聊 Git LFS。 - 有不认识的 untracked 文件时,不要 `git add .` / `git add -A`。 按文件名加。