Git Work

Git 工作流 SOP（dev + release 发版管理）

详细示例见 examples.md，命令速查见 reference.md。

两块正交内容：

• 模式一~五：Spec 工作分支生命周期（短分支 → PR → 合并即删）
• 模式六：发版分支与 tag 管理（长期 release 分支 + 版本 tag）

核心约定

R&K Flow 采用 dev + release 集成与发版工作流，并对合并审查进行平台中立的 PR/MR 抽象：

1. 主干分支（<main>）：始终保持生产就绪与已发布状态，默认读取 git symbolic-ref refs/remotes/origin/HEAD（常见为 master 或 main），严禁直接在主干上实现。
2. 日常集成开发分支（dev）：在研 Spec 的日常集成线。所有常规 Spec 分支均从 dev 切出，并通过 PR/MR 合入 dev。
3. 版本提测集成分支（release/<version>）：版本提测冻结时从 dev 切出，只接收该版本的缺陷修复（fix/*），完成全量集成验证。
4. 版本发版：release/<version> 通过 PR/MR 合入 <main>，打正式发布 Tag（vX.Y.Z），并强制反向合流回 dev。
5. 线上热修（hotfix/*）：严格从对应生产环境的发布 Tag 切出，验证通过后合入 <main> 打 Patch Tag，并强制双向回流 dev 与当前在研的 release/* 分支。
6. 长期支持线命名：长期定制或客户维护线统一命名为 support/<line>，不使用 release/*，避免与临时提测分支冲突。
7. PR / MR 平台中立：GitHub 称为 PR，GitLab 称为 MR。元数据统一记录请求类型、URL、源分支、目标分支与审查结果。

在 Spec 生命周期中的位置

textCopy code
spec-start
  → git-work：从 `dev` 创建 Spec 工作分支（base_branch: dev）
  → plan.html 记录 git_branch、base_branch: dev、pr_url

spec-update
  → git-work：确认当前分支与 plan.html 的 git_branch 一致
  → update-xxx.html 继承 plan.html 的 git_branch、base_branch、pr_url

开发与测试阶段
  → 始终留在当前 Spec 分支
  → 必要时推送远程分支，方便团队协作

spec-end / spec-update 收尾
  → git-work：提交、推送当前 Spec 分支
  → 面向 `dev` 创建 PR/MR；spec-update 仅在 Spec 准备整体交付时创建/更新 PR/MR
  → 记录 PR/MR URL，并通过 amend 并入同一次提交

PR/MR 合并后
  → git-work：同步 `dev`，删除本地和远程工作分支

分支命名

格式：

textCopy code
<type>/spec-<YYYYMMDD-HHMM>-<ascii-slug>

示例：

textCopy code
feat/spec-20260428-1430-user-auth
fix/spec-20260428-1530-login-timeout
docs/spec-20260428-1600-rk-flow-docs
refactor/spec-20260428-1700-db-layer
test/spec-20260428-1800-audit-log

类型映射：

规则：

• 分支名必须 ASCII，中文任务名保留在 Spec 目录名
• slug 使用小写短横线，不能包含空格
• 同一个活跃 Spec 的所有提交和 update 留在同一分支
• 如果原 Spec 分支已合并/删除，后续需求默认新建 Spec；只有用户明确要求独立 PR 时才创建新分支承接 update

分支命名反例（禁止把版本号塞入分支名）

版本号与分支关系规则表

模式一：启动 Spec 分支

由 spec-start 在正式写文档前调用。spec-update 默认不调用本模式，除非用户明确要求为该 update 创建独立 PR。

1. 检查仓库

bashCopy code
git rev-parse --is-inside-work-tree
git remote -v
git status --short

如果不是 Git 仓库：向用户说明无法执行 GitHub Flow，询问是否继续无分支模式。

如果工作区不干净：

• 若改动属于当前即将启动的 Spec，先让用户确认是否纳入本分支
• 若改动无关，先提交、stash 或切换到干净工作区
• 不要在脏工作区直接切换到 dev

2. 同步日常开发集成线 dev

日常在研 Spec 默认以 dev 分支为开发起点与合并目标：

bashCopy code
git switch dev
git pull --ff-only origin dev

如果仓库尚未创建 dev，先从主干分支（由 git symbolic-ref refs/remotes/origin/HEAD 读取，记作 <main>）创建 dev：

bashCopy code
git switch -c dev
git push -u origin dev

3. 创建工作分支

bashCopy code
git switch -c <branch-name>

团队协作或并发开发时，立即推送远程分支：

bashCopy code
git push -u origin <branch-name>

4. 输出给 Spec 文档

把以下元数据传给 spec-write：

yamlCopy code
git_branch: <branch-name>
base_branch: dev
pr_url:

base_branch 统一记录为 dev。

模式二：并发开发使用 worktree

当同一仓库需要同时开发多个 Spec，不要在同一个 working tree 里来回切分支。使用 worktree：

bashCopy code
git switch dev
git pull --ff-only origin dev
git worktree add ../<repo>-<spec-slug> -b <branch-name> dev

进入新 worktree 后再运行对应的 Spec 流程。每个并行 Spec 独占一个目录和一条分支。

模式三：复用 Spec 分支

由 spec-update 在创建 update 文档前调用。

1. 读取 plan.html Git 元数据

报告是 HTML，Git 元数据在 <head> 的 <meta name="rk:*"> 里（.rk-meta 是同字段的人可读镜像）：

htmlCopy code
<meta name="rk:git-branch"  content="<branch-name>">
<meta name="rk:base-branch" content="{base_branch}">
<meta name="rk:pr-url"      content="">

2. 校验当前分支

bashCopy code
git branch --show-current
git status --short

规则：

• 当前分支必须等于 plan.html 的 rk:git-branch
• 如果当前分支是 dev 或主干分支，停止并切回 Spec 分支
• 如果原分支已合并或不存在，默认不继续 spec-update；应新建 Spec 或让用户明确选择独立 update 分支
• update-xxx.html 继承 plan.html 的 rk:git-branch / rk:base-branch / rk:pr-url

模式四：完成 Spec 分支

由 spec-end 或 spec-update 收尾时调用。

1. 确认当前分支

bashCopy code
git branch --show-current
git status --short

禁止直接在 dev 或主干分支上提交 Spec 成果。若当前分支不是 plan/update 文档记录的 git_branch，先确认原因。

2. 审查变更

bashCopy code
git diff --stat
git diff

确认包含：

• 代码实现
• 测试与日志/审计证据
• Spec 文档、summary/test-report/review/debug/update 文档
• 必要的 AGENTS.md / .agents/rules/ 规范更新
• 归档目录移动（新 Spec 完成时）

3. 提交

bashCopy code
git add .
git commit -m "<type>: <summary>"

提交信息规则：

• 使用 feat:, fix:, docs:, refactor:, test:, chore:
• 第一行不超过 72 字符
• 正文写清 Spec 路径、测试结果、关键决策

4. 推送

bashCopy code
git push -u origin <branch-name>

5. 创建或更新 Pull Request

spec-end 默认创建 PR。spec-update 默认只提交并推送当前 Spec 分支；如果该 Spec 已准备整体交付，或用户明确要求，则创建/更新 PR。

如果可用，优先使用 GitHub CLI：

bashCopy code
gh pr create --base dev --head <branch-name> --title "<PR title>" --body-file <pr-body.md>

如果没有 gh，输出 GitHub compare URL，让用户手动创建 PR：

textCopy code
https://github.com/<owner>/<repo>/compare/dev...<branch-name>

PR 内容至少包含：

• Spec 路径
• 实现摘要
• 测试结果
• 风险与回滚方式
• 关联的经验/规范更新

6. 记录 PR URL

如果拿到 PR URL，写回对应文档：

yamlCopy code
pr_url: https://github.com/<owner>/<repo>/pull/<number>

写回后并入同一次提交（spec-end / spec-update 收尾的硬要求：全部处理完只提交一次，不产生第二次提交）：

bashCopy code
git add <spec-docs>
git commit --amend --no-edit
git push --force-with-lease origin <branch-name>

说明：

• --amend --no-edit 把 pr_url 写回并进刚才那次提交，git 历史保持一次提交
• --force-with-lease 只允许覆盖自己刚推送的引用；若远程分支已被他人改动会拒绝并报错，不会误覆盖别人的提交
• 仅限「本流程刚创建并推送的 Spec 分支」这一场景；其它任何 force push 仍是门禁（见 spec-end 停止条件）

模式五：PR/MR 合并后清理

只有在面向 dev 的 PR/MR 已合并后执行：

bashCopy code
git switch dev
git pull --ff-only origin dev
git branch -d <branch-name>
git push origin --delete <branch-name>

如果本地分支无法删除，先确认 PR/MR 是否已合并，避免误删未合并成果。

模式六：发版管理与版本集成分支（dev + release + support）

分支模型矩阵

临时提测分支 release/<version> 生命周期

1. 冻结拉出：当属于该版本的全部规划 Spec 合入 dev 后，由 version-release 从 dev 拉出 release/<version>。
2. 提测修复：若测试发现集成 Bug，切 fix/* 分支直接 PR/MR 合入 release/<version>。
3. 发布合流：整体验收通过后，PR/MR 合入 <main> 并打正式不可变 Tag（vX.Y.Z），同时强制反向合并回 dev。
4. 收尾清理：版本收尾（version-end）交付归档后，删除本地与远程的 release/<version> 分支。

模式七：线上紧急热修（Hotfix）与强制回流

线上突发严重缺陷时走此紧急通道：

bashCopy code
# 1. 确认线上实际运行的 tag（严禁随意从 HEAD 切热修）
git checkout <production-tag>

# 2. 创建热修分支
git switch -c hotfix/<slug>

# 3. 修复、验证通过后提交
git commit -m "fix(hotfix): 修复线上特定严重缺陷"

# 4. 通过 PR/MR 合入主干 <main>，并打出 Patch Tag（如 v1.6.1）
git checkout master
git pull origin master
git merge hotfix/<slug> --no-ff -m "merge: hotfix/<slug> 紧急修复合入"
git tag -a v1.6.1 -m "hotfix: v1.6.1"
git push origin master v1.6.1

# 5. 强制回流开发线 dev（防止下一个版本带回同一 Bug）
git checkout dev
git pull origin dev
git merge master --no-edit
git push origin dev

# 6. 若存在活跃的在研提测分支 release/<v>，同样合流
git checkout release/<v>
git merge master --no-edit
git push origin release/<v>

# 7. 删除热修临时分支
git branch -d hotfix/<slug>

发版流程

bashCopy code
# 1. 修复先进主干（master）
git switch master && git commit ... && git push

# 2. cherry-pick 到目标发布线
git switch support/<line>
git cherry-pick <commit>

# 3. 跑测试（定制线注意区分既有失败，见下）
<项目测试命令>

# 4. 打 annotated tag 并推送
git tag -a <version> -m "<说明>"
git push origin support/<line> <version>

tag 说明必须写清：改了什么、实测数据、cherry-pick 来源、是否已部署。 只用 annotated tag（-a），轻量 tag 不带作者、日期和说明。

tag 指向「发版的代码」，不追 HEAD

release 分支允许存在不产生新版本号的提交：规范、文档、Spec 报告等不改变 运行行为的内容。这类提交后 tag 落后于 HEAD，属正常状态。

判断标准：这笔提交会改变构建出的产物行为吗？

核对方法：

bashCopy code
git diff --name-only <tag> support/<line>

差异只含「否」类文件即正常；混入源码说明漏打 tag。

镜像标签必须等于 git tag

构建产物（Docker 镜像等）的标签必须与 git tag 同名，不得自行取名：

bashCopy code
git switch --detach <version>
docker build -t <image>:<version> .
# 部署侧 .env: IMAGE_TAG=<version>

这样从服务器可直接反查代码：

bashCopy code
ssh <server> "grep '^IMAGE_TAG=' <path>/.env"   # 得到 <version>
git switch --detach <version>                    # 就是线上那份代码

实际踩过：生产跑 IMAGE_TAG=tut-v1.0.5 但 git 中无此 tag，镜像实际由某个 裸 commit 构建，线上版本与代码彻底失去对应关系，只能靠人工记录。

更强的做法是把 commit 烘进产物：构建时 --build-arg GIT_COMMIT=$(git rev-parse HEAD) 写入环境变量，运行时可直接查询，连命名约定都不必依赖。

定制线的既有测试失败

定制线常因改了共享文件而让主线的守卫测试恒失败。发版前必须先建立基线：

bashCopy code
# 在 cherry-pick 前的提交上跑一次，记下 failed 数
git switch --detach <cherry-pick 前的 commit>
<测试命令>

判据是 failed 数不增加，不是「全绿」。把已知恒失败项及其原因记进项目 速查表，否则每次发版都要重新判断哪些失败是无害的。

清理带版本号的旧分支

迁移到本模型时，旧的 release/vX 分支可以删——但删前必须逐条验证每个 分支的 HEAD 提交有 tag 或保留分支覆盖：

bashCopy code
# 该分支是否已被某条保留分支包含
git merge-base --is-ancestor <old-branch> support/<line>

# 独有提交数，必须为 0
git log --oneline <old-branch> --not master support/<line> | wc -l

两项都通过才能删。删分支不丢提交的前提是版本点已被 tag 钉住， 没有 tag 覆盖的分支删掉就是丢代码。

每次发版后更新速查表

在项目的 AGENTS.md 维护一张表，记录每条线的当前 tag、部署位置、版本历史。 发版即更新一行。没有这张表，过几周就会出现「哪个版本部署在哪、对应哪份代码」 说不清的情况——这正是本模式要解决的问题。

常见阻塞

禁止事项

• 不要在 dev 或主干分支上直接实现 Spec
• 不要在脏工作区切换分支
• 不要把多个无关 Spec 混在同一分支
• 不要在测试失败时创建 PR，除非 PR 明确标记为 Draft
• 不要自动合并 PR，除非用户明确要求

发版相关（模式六）：

• 不要新建带版本号的分支（release/v1.0.4、support/<line>-v1.0.5）
• 不要用轻量 tag 发版，必须 git tag -a
• 不要为纯文档提交打新版本号 tag（适用于业务代码仓库；R&K Flow 本仓库作为工作流与技能规范产品，框架发版时豁免）
• 不要让产物标签与 git tag 不同名
• 不要在没有 tag 覆盖的情况下删分支
• 不要用「全绿」作为定制线的发版判据，用「failed 数不增加」
• 不要移动或复用已推送的 tag（会改变已发布版本的含义）
• push tag 时必须显式指定 tag 名（如 git push origin <tag>），严禁使用 git push --tags，避免误推本地临时或脏 Tag