Files
praxis/docs/03-git-workflow.md
T
阿白叔andClaude Opus 4.7 dfa84743f9 docs: add product project spec, distinguish date vs semver tags
Distill task_assistant's COLLABORATION_AND_RELEASE_WORKFLOW into a
team-wide product project spec and clarify when each tag style applies.

- Add docs/08-product-spec.md: semver triplet (internal/display/tag),
  manifest schema, dist-channel separation, user-confirmed update
  flow, feedback/log handling, sensitive-info scan, release flow,
  minimum delivery checklist
- docs/03-git-workflow.md: split tagging into spec (YYYYMMDD) vs
  product (vX.Y.Z) sections, link to 08
- README.md, CLAUDE.md, AGENTS.md: update versioning section and doc
  index to reference 08

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
2026-05-20 14:45:28 +08:00

154 lines
5.5 KiB
Markdown

# 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 风格:
| 项目类型 | Tag 格式 | 例子 | 用在哪儿 |
| -------- | ------------------- | -------------------------- | ------------------------------------- |
| 规范类 | `YYYYMMDD[-N]` | `20260520`、`20260520-2` | team-guide、规约文档、内部约定仓库 |
| 产品类 | `vX.Y.Z` | `v0.2.4` | task_assistant、有版本和发行包的产品 |
判断标准:会有"用户"拿到这个项目的版本化产物——产品类。否则——规范
类。详细规则见 [`docs/08-product-spec.md`](08-product-spec.md)。
每个 tag 是 `main` 某一时刻的快照——值得指着说"我们就按这版来"。
通用规则(两类都适用):
- 只在 `main`(规范类)或 `dev`(产品类)上打 tag。功能分支打 tag
是 smell。
- 用 annotated tag,不用 lightweight。`git tag -a` 加一两句说自上次
tag 以来改了什么。
- Tag 一旦推到远端就不能改、不能删、不能 force-tag。错了就再切一个。
- Tag commit、push tag、告诉大家 tag 名字——这就是发布。
规范类专属:一天最多一个 tag。同一天再切一个,加 `-N` 后缀:
`20260520-2`、`20260520-3`。
产品类专属:semver 三元组、产品 README 必备版本字段同步、tag
message 用 `<Project> V<x.y.z>`——细则见
[`docs/08-product-spec.md`](08-product-spec.md)。
切 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
```
切 tag(产品类):
```bash
git checkout dev
git pull --ff-only <remote> dev
git tag -a v0.2.4 HEAD -m "<Project> V0.2.4"
git push <remote> v0.2.4
```
查看 / 对比:
```bash
git tag --sort=-creatordate # 按时间倒序
git show 20260520 # 看一个 tag 里有什么
git log --oneline 20260513..20260520 # 两个 tag 之间改了什么
```
什么时候切 tag(规范类):
- 本仓库的 docs 改了,队友需要重新读。
- 加了、删了或重组了 template。
- 新的约定正式生效(不是还在讨论)。
什么时候**不**切 tag(规范类):
- 改错别字、调格式、修死链 → 直接 push 到 `main`。
- 还在讨论的草稿 → 走 PR,不打 tag。
产品类切 tag 跟着发版走,触发条件由[最低交付标准](08-product-spec.md#最低交付标准每次可给别人用的版本)
决定。
## 不要做的事
- 不要 `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`。
按文件名加。