Files
praxis/docs/03-git-workflow.md
T
阿白叔andClaude Opus 4.7 154f592f3c docs: split language by audience, add Codex / AGENTS.md spec
Language policy: Chinese for human-facing files (README, docs/,
human-fillable templates), English for AI-facing files (CLAUDE.md,
AGENTS.md, AI templates). Commits / PRs / branches / tags stay
English.

- Translate docs/01-06 to Chinese
- Translate README.md, PR / handoff / project README templates to Chinese
- Drop README.en.md (redundant once language policy is explicit)
- Rewrite CLAUDE.md and CLAUDE.md.template under the new policy
- Add AGENTS.md (root) and templates/AGENTS.md.template for Codex
- Add docs/07-codex.md covering Codex usage and AGENTS.md / CLAUDE.md sync rules

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
2026-05-20 09:44:15 +08:00

127 lines
4.3 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 03 — Git 工作流
小团队,流程从轻。分支、commit、PR、review、tag。
## 分支
- `main` 永远可发。不直接 push,没有例外。
- 功能分支:`<owner>/<short-slug>` —— 比如 `bai/auth-retry`、
`bai/eval-agent-rerun`。小写、连字符、你的 handle 做前缀。
- 长期集成分支:`integration/<topic>` —— 团队同意才用。
- 合并完删分支。老分支会污染搜索结果。
## Commit
格式:
```
<area>: <祈使句小结,60 字符以内>
<可选 body —— 写改了什么、为什么,不写怎么改>
```
- `<area>` 是目录或组件,小写:`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 留到最后,让它明显是闸门。
作者收尾:
- 每条评论都回应,哪怕只是"同意,已在 <commit> 修"。
- 不同意写出来 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`。
按文件名加。