name: repo-gitflow-workflow description: 从 Terra-Wiki 蒸馏的通用 gitflow 工作流：三段式分支模型、两条铁律、Conventional Commits、发布与热修流程、分支保护落地

项目开发规范蒸馏：gitflow 分支模型与发布流程

长期分支只有三个角色：main（生产，每个提交对应线上可运行状态）、develop（集成，日常合并目标）、<type>/<name>（工作分支）。
工作分支按意图命名：feature/ bugfix/ chore/，流程完全一致，前缀只区分意图。
铁律一：功能分支一律从 develop 切出、合回 develop。main 上每个提交都要可发布，未经集成验证的东西混进去就破坏了这个承诺。
铁律二：只有 release/* 与 hotfix/* 能进 main，它们是发布边界的唯一入口。
release/<version> 从 develop 切出，只放发布前修补（文案、依赖、迁移定稿、版本号回写），合回 develop（回灌）与 main（发布）；hotfix/<version> 从 main 切出（develop 上可能有未验证功能），修完同时合回 main 与 develop——回灌漏了 develop，下个版本会把这个 bug 再带上线。
命名 <type>/<short-kebab-description>：小写短横线、不用中文；release/hotfix 后半段是版本号不带 v。
版本语义化 MAJOR.MINOR.PATCH，与 package.json 的 version 一致；tag 只打在 main，形如 v0.2.0。

节奏：从最新 develop 切分支 → 开发自测（typecheck+test）→ 小步提交 → PR 到 develop → CI 绿 + review 通过 → --no-ff 合并 → 删源分支。
main 与 develop 只接受 --no-ff 合并、保留发布边界节点；不 force push、不直接 push。
分支落后用 rebase 或 merge develop 同步，二者选一、团队内一致。

Conventional Commits：<type>(<scope>): <subject>，type ∈ feat/fix/chore/docs/test/refactor/perf/build/ci，scope 取模块名，subject 祈使句、动词开头、≤72 字符、结尾不加句号。
一次提交只做一件事，重构与功能不混——否则 review 看不出意图，revert 也切不干净。
破坏性变更在 body 写 BREAKING CHANGE: <说明>；body 写"为什么这么改"，不是"改了什么"。

main 与 develop 都要求：必须走 PR、指定 CI check 必须过、禁 force push、禁删除、合并后自动删源分支；main 额外要求线性历史 + ≥1 个 approve。
develop 不强制线性历史——release/hotfix 的 --no-ff 回灌本来就有合并节点，规则别跟流程打架。
保护规则的 required check contexts 必须与 CI job 名一致，改 job 名要同步改，否则 PR 永远卡在"等待检查"。