Skip to content

Git 提交 / 发版 / 版本号 / 分支 统一规则 ​

适用范围:根仓 CoreFlow 与全部子前端 / 子项目(oauth-web、retroweb、posecraft、firewall、admin……)。 新项目接入:拷贝 scripts/release-web.mjs + 本文档到新仓库,见第五节。

配套工具:

仓库形态发布脚本说明
根仓 CoreFlow(后端 + npm 包)scripts/release.mjs三通道:git tag / GitHub Release / npm(packages/log)
子前端 / 独立仓scripts/release-web.mjs两通道:git tag / GitHub Release;--npm 可选开启 npm

两个脚本判据完全一致(同一套 Conventional Commits 规则),差别只在通道与默认值。


一、提交规范(Conventional Commits) ​

1.1 格式 ​

<type>(<scope>): <subject>

[可选的 body:写清楚"为什么",尤其是坑与决策]

[可选的 footer]
  • subject 用中文或英文均可,不超过 72 字符,结尾不加句号;
  • body 与 footer 之间空一行;footer 形如 Key: value。

1.2 type 表(判据只认这些前缀) ​

type含义是否触发发版
feat新功能✅ minor
fix缺陷修复✅ patch
perf性能优化✅ patch
refactor重构(行为不变)❌
docs文档❌
test测试❌
chore杂项(依赖、构建配置)❌
style格式(不影响逻辑)❌
ciCI 配置❌
build构建系统❌
revert回滚❌

不匹配以上前缀的提交归入 other,不触发发版。标题写错前缀 = 该提交不计入发版判据。

1.3 scope 约定 ​

scope 写受影响的面,不写文件名:

场景scope 示例
后端业务域retroweb、oauth21、firewall、user
前端页面 / 模块login、theme、router、api
工程化ci、release、deps、build
跨项目拆分可省略 scope,如 chore: oauth21 拆分为独立仓库
feat(api)!: 授权接口改为要求 PKCE

BREAKING CHANGE: /oauth/authorize 不再接受无 code_challenge 的请求,
调用方必须先升级 SDK。
  • 判定正则:/^BREAKING[ -]CHANGE:/m——必须行首且带冒号;
  • 🔴 不可退化成子串匹配:正文里"提到"这个词(例如写本规则自身)会把 minor 误升成 major,真实仓库上发生过;
  • !: 简写(feat(api)!: …)与 footer 等价,任一出现即 major。

1.5 敏感词自查(Release 说明对公网可见) ​

标题 / 正文含下列表述的提交,发版时脚本会单独列出要求人工确认:

漏洞、泄露、未授权、越权、注入、绕过、CVE-*、token、secret、password、密钥、凭证

修复安全问题的提交,fix 标题写" hardening / 加固"而非漏洞细节,细节放 body(body 默认不进 Release 说明)。


二、版本号规则 ​

2.1 语义化版本(SemVer) ​

v{major}.{minor}.{patch}
档位递增规则触发条件
majorX+1.0.0破坏性变更(footer 或 !:)
minorX.Y+1.0含任一 feat
patchX.Y.Z+1仅 fix / perf
—不发版仅 chore/docs/test/style/ci/refactor/build/revert

起算基线 = 最近的 tag(复盘 / 补发用 --from <ref> 显式指定)。

2.2 版本源是 git tag,package.json 单向跟随 ​

  • 🔴 不要反过来拿 package.json 的 version 推版本号——tag 才是唯一版本源;
  • 🔴 对齐动作由脚本完成,不靠人记:--apply 会把根仓(子前端为各自仓)package.json 的 version 写成新版本号,并单独提交 chore(release): X.Y.Z,再打 tag —— 顺序不能颠倒,否则 tag 指向的提交里没有新版本号和新 CHANGELOG;
  • dry-run 阶段只打印 将对齐 package.json version a → b,不落盘;
  • 子前端若没有 package.json(纯静态仓),此规则自动跳过。

为什么强调顺序:tag 是不可变的指针,一旦指向"还没更新版本号"的提交,之后无论怎么提交 都对不上 tag 名 == package.json version 这条判据,release-npm.yml 会当场红。

2.3 tag 命名与创建方式 ​

  • 格式:v1.2.3,必须带 v 前缀;
  • 必须 annotated(git tag -a),message 写版本摘要——Release 说明的初稿来自提交分类,tag message 是给人看的 changelog;
  • tag 跟随 main 一起推;推送判定一律以 git ls-remote 为准,不信退出码(本机 push 有"零输出假成功"前科);
  • 删除远端 tag:git push origin :refs/tags/vX.Y.Z(仅限发错且未生成 Release 的场景)。

三、分支(支线)模型 ​

3.1 分支总表 ​

分支生命周期规则
main唯一长期分支发版唯一入口;随时可部署;禁止 git push --force
feature/*短支线,合并即删一个需求 / 一个提交主题一条;从 main 切出
hotfix/*短支线,合并即删生产紧急修复;从出问题的 tag 切出,修完回 main 并补 patch 版
docs/*、chore/*可选短支线纯文档 / 杂项改动,避免污染 feature 命名
main ─────●──────●──────────●──────●─── (tag: v1.0.0) ──▶
           │           ▲                    │
           └─ feature/login ┘                └─ hotfix/sign-key ─┐
                                          (从 v1.0.0 切)          │
                                                              main ◀┘ (tag: v1.0.1)

3.2 主干规则 ​

  • 🔴 发版只允许在 main 上进行(脚本强制检查,非 main 直接拒绝);
  • 单人开发 + 并行任务允许工作区有未提交改动,但发版执行时必须显式 --allow-dirty(语义:"本次要发的内容已提交,剩余脏文件属于别的任务");
  • 提交前跑一遍项目的 lint / test——CI 之外的最后一道闸。

3.3 支线规则 ​

  • 命名:feature/<主题>、hotfix/<主题>,小写连字符;
  • 一个支线只做一件事;做完立即合并回 main 并删除远端支线(git push origin --delete <branch>);
  • 合并用 --no-ff(保留支线拓扑,changelog 才读得出来);
  • 支线不打 tag——tag 只从 main 的提交打。

3.4 仓库族协作(2026-10-31 起:前后端彻底分仓) ​

前端工程已全部移出本仓索引、各自独立,不再是本地嵌套目录:

仓远程与本仓关系
CoreFlow(本仓)yijiu2025/CoreFlow只含后端(src/、migrations/、scripts/、docs/)
oauth-webyijiu2025/oauth-web独立仓(原 oauth21/ 前端)
其他前端各自远程posecraft / admin / poseadmin / firewall / phonecopy
  • 前端改动在本仓无效:干净检出里已没有这些目录,git status 也不会再出现它们;
  • 每个前端仓独立维护自己的 tag 线(各自从 v1.0.0 起算,与本仓版本号无关);
  • 本仓 .gitignore 保留 /oauth21/、/posecraft/、/admin/、/poseadmin/、/firewall/、 /phonecopy/ 六条带前导斜杠的规则 —— 目的是让本地同时检出前后端时不被误提交, 同时不能误伤后端同名目录(src/api/oauth21/、src/app/firewall/、migrations/retroweb/ 等), 这就是必须带前导斜杠的原因 —— 写成 oauth21/ 会连 src/api/oauth21/ 一起忽略且不报错;
  • packages/theme-core 仍是 git submodule(不是独立仓),提交前注意它的指针是否漂移。

3.5 GitHub 侧保护设置(每个仓建仓后做一次) ​

  1. Settings → Branches → Add rule:main 勾选 Require a pull request before merging、Block force push;
  2. Settings → General:Features 只留 Issues / Releases /Discussions(按需);
  3. 建仓后先在本地 git push -u origin main 再开保护,避免空仓规则不生效。

四、发布流程(脚本用法) ​

🔎 端到端发布 checklist(更新 CHANGELOG → 完善文档 → 对齐版本号 → 跑门禁 → 发版 → 镜像 → 校验) 见 fullstack-rules 技能 references/release-checklist.md。本节是脚本用法与行为约定,checklist 是 「一次完整发布」的动作顺序。

4.1 用法(所有仓统一) ​

bash
# 预览(默认,不做任何写操作)—— 每次发版前先跑这个
node scripts/release.mjs            # 根仓
node scripts/release-web.mjs        # 子前端 / 独立仓

# 执行:打 annotated tag + 推 main 与 tag + 建 GitHub Release
node scripts/release.mjs --apply
node scripts/release-web.mjs --apply

# 复盘 / 补发:显式指定起算 ref
node scripts/release-web.mjs --from v1.0.0

# 子前端如需发 npm(默认不发)
node scripts/release-web.mjs --apply --npm

# 工作区有并行任务遗留改动时放行(语义:要发的内容已提交)
node scripts/release-web.mjs --apply --allow-dirty

4.2 脚本行为约定(两个脚本一致) ​

  1. 默认 dry-run:不可逆操作(推 tag、建公开 Release、npm publish)一律先预览;
  2. 分支闸:非 main 拒绝执行;
  3. 脏工作区闸:--apply 时有未提交改动且无 --allow-dirty 拒绝执行;
  4. 判据:破坏性 → major;feat → minor;仅 fix/perf → patch;其余不发;
  5. 漂移自愈:tag 已推而 Release 缺失时,重跑脚本自动补建(不依赖"有无新提交"的判断);
  6. 推送判定:push 后一律 git ls-remote 核对远端 SHA 与 tag,不信退出码;成功同步后自动跑 fix-packed-refs.mjs(本机不写松散 ref,不修则 git status 长期谎报 ahead);
  7. 凭据:GitHub token 依次取 $GITHUB_TOKEN / $GH_TOKEN / git credential manager(GCM),无需 gh CLI;
  8. 敏感词:命中 1.5 节词表的提交标题会被列出,要求人工确认后才可外发;
  9. CHANGELOG 自动提升(两个 release 脚本):--apply 时把 CHANGELOG.md 的「未发布(Unreleased)」区块提升为 ## X.Y.Z — YYYY-MM-DD 并重建空区块;区块为空或文件不存在则不提升、预览时警告;
  10. package.json 自动对齐(两个 release 脚本):--apply 时把根/本仓 package.json 的 version 对齐到新 tag(单向跟随,见 2.2);子仓的 lock 文件一并对齐,不再手动改。

4.3 发版后的校验(脚本已自动收尾,剩人工核对) ​

  • CHANGELOG / package.json 已由脚本 --apply 自动处理,检查生成结果是否符合预期即可;
  • 在 Release 页面检查说明是否符合预期(尤其敏感词提交);
  • 有 Docker 镜像的仓:等 docker-publish workflow 完成,核对 GHCR / Docker Hub 的 <version> 与 latest tag(见 release-checklist.md §六);
  • 若 push 提示远端不一致:重试推送并用 git ls-remote origin main 复核——超时不等于失败。

五、新项目接入清单(5 分钟) ​

bash
# 1. 拷两个文件进新仓库
cp <任意现有仓>/scripts/release-web.mjs <新仓库>/scripts/
cp <任意现有仓>/docs/standards/git-release-rules.md <新仓库>/docs/   # 或 docs/

# 2. 建远程仓并关联(GitHub 先建空仓,勿自动生成 README——本地已有)
git init -b main && git add -A && git commit -m "feat: 初始提交"
git remote add origin https://github.com/<user>/<repo>.git
git push -u origin main

# 3. 按 3.5 节配好分支保护

# 4. 接入 CI 门禁(前端家族):分发共享门禁三件套 + 写入口 ci.yml
node <fullstack-rules 技能路径>/scripts/distribute-ci.mjs <新仓库路径>
#    规范:fullstack-rules → references/ci-conventions.md(入口骨架 / 顺序口径 / 专属关卡)

# 5. 建 docs 总入口:docs/README.md 逐文档登记,拷校验脚本并挂 CI
cp <fullstack-rules 技能路径>/assets/docs/check-docs-index.mjs <新仓库>/scripts/
node scripts/check-docs-index.mjs docs   # 退出码 0 方可提交
#    规范:fullstack-rules → references/docs-conventions.md(两级入口体系 / 双写 / 死链口径)

# 6. 首次发版
node scripts/release-web.mjs          # 预览:应判定 minor 并给出 v0.1.0 或 v1.0.0
node scripts/release-web.mjs --apply  # 执行

💡 首版版本号习惯:后端 / 平台型从 v0.1.0 起步(内部迭代),对外发布的前端从 v1.0.0 起步(oauth-web 即此例)。


六、常见问题 ​

现象原因处理
提交了 feat 却不发版标题前缀不在 1.2 表内(如 feature:、新增:)改前缀;已推送的用 git commit --amend 或认栽等下次
minor 被误升 major正文写了 BREAKING CHANGE: 但不在行首 / 带冒号形式之外按 1.4 节,只认行首+冒号
git status 长期显示 ahead本机不写松散 ref跑 node ~/.workbuddy/tools/fix-packed-refs.mjs <远端SHA>
tag 推了但没 Release网络中断 / token 超时重跑同一脚本,会自动补建
嵌套仓改动提交不进根仓在根仓目录执行了提交cd 进嵌套仓目录重新提交

基于 GPL-3.0 许可发布