| name | git-auto-release |
| description | 在需要根据本地改动自动完成提交、推送和语义化打标时使用,尤其适用于发布流程要求 CHANGELOG 存在对应版本条目的场景。 |
Git 自动发布
概述
该技能用于规范一套完整发布流程:分析当前改动、生成合适提交、推送分支更新、计算下一个语义化版本标签、更新变更日志条目并推送标签。
它适用于通过 v* 标签触发自动发布、且要求 CHANGELOG.md 中必须包含对应 [x.y.z] 版本段落的仓库。
何时使用
- 需要一次性完成提交 + 推送 + 打标签。
- 希望标签版本由改动影响自动推导,而不是手工指定。
- 发布流水线会校验 CHANGELOG.md 是否包含对应 [version] 条目。
以下场景不建议使用:
- 分支策略禁止直接推送。
- 用户明确要求手动指定版本号。
输入项
- 目标分支(默认:当前分支)。
- 远程名称(默认:origin)。
- 可选的发布说明关注点(用于优化 changelog 条目)。
工作流
- 校验仓库状态。
- 暂存相关文件。
- 推断提交类型并生成提交信息。
- 基于最近 vX.Y.Z 标签计算下一版本。
- 确保 CHANGELOG.md 存在 [newVersion] 条目。
- 将代码改动与 changelog 一起提交。
- 推送分支。
- 创建并推送标签。
- 校验本地与远程结果。
步骤细则
1. 校验仓库状态
执行:
git rev-parse --is-inside-work-tree
git fetch --tags --prune
git status --short
git rev-parse --abbrev-ref HEAD
Rules:
规则:
- 如果没有改动,停止并报告 no changes to release。
- 如果存在冲突,停止并要求先手动解决冲突。
2. 暂存相关文件
默认行为:
git add -A
如果用户要求部分发布,只暂存指定路径。
3. 基于已暂存改动推断提交信息
检查已暂存内容:
git diff --cached --name-status
git diff --cached -- .
提交类型判定:
- feat:新增用户可见功能或能力。
- fix:修复缺陷或回归问题。
- docs:仅文档变更。
- refactor:不改变行为的结构或内部重构。
- chore:工具链、构建或基础设施维护。
标题格式:
<type>: <short summary of main change>
如果是混合改动,按以下优先级选择最高影响的类型:
feat > fix > refactor > docs > chore。
4. 从标签计算下一版本
查找最近语义化标签:
git describe --tags --abbrev=0 --match "v[0-9]*.[0-9]*.[0-9]*"
版本基线规则:
版本提升规则:
- Major:存在破坏性变更信号。
- Minor:至少包含一个 feat 且不存在破坏性变更。
- Patch:其他所有情况。
破坏性变更信号(满足任一即可):
- 提交头包含 !(例如 feat!: 或 refactor!:)。
- 暂存内容中出现 BREAKING CHANGE。
- 用户明确说明存在不兼容行为或 API 变更。
语义化版本计算:
- Major:X+1.0.0
- Minor:X.Y+1.0
- Patch:X.Y.Z+1
标签格式必须是 v。
5. 更新 CHANGELOG 条目
检查目标版本条目是否已存在:
git grep -n "^## \[<newVersion>\]" CHANGELOG.md
如果不存在,在当前最上方已发布版本之前新增段落(通常位于 ## [Unreleased] 之后):
## [<newVersion>] - <YYYY-MM-DD>
### Changed
- <auto-generated summary from staged diff>
要求:
- 标题必须严格匹配 ## [x.y.z](不带 v)。
- 变更条目应简洁,面向用户可读。
6. 提交
将所有已暂存发布改动(代码 + changelog)一起提交:
git commit -m "<type>: <summary>"
7. 推送分支
git push <remote> <branch>
8. 创建并推送标签
git tag "v<newVersion>"
git push <remote> "v<newVersion>"
9. 校验
git status --short
git log --oneline --decorate -n 5
git ls-remote --tags <remote>
成功标准:
- 工作区干净。
- 目标分支上存在本次提交。
- 新标签在本地和远程都存在。
- CHANGELOG.md 中存在准确的 ## [] 条目。
快速决策表
| 观察到的改动 | 提交类型 | 版本提升 |
|---|
| 破坏性 API 或行为变更 | feat! 或 refactor! | Major |
| 新增能力 | feat | Minor |
| 仅缺陷修复 | fix | Patch |
| 仅重构/文档/维护 | refactor/docs/chore | Patch |
输出模板
完成后使用如下固定格式报告:
Release completed.
- Branch: <branch>
- Commit: <sha> <subject>
- Previous tag: <tag or none>
- New tag: v<newVersion>
- Bump reason: <major|minor|patch + why>
- Pushed: branch and tag
- Changelog: CHANGELOG.md includes [<newVersion>]
常见失败处理
- 推送被拒绝(受保护分支):停止并要求用户授权或切换发布策略。
- 标签已存在:基于远程最新标签重新计算版本,并重试一次。
- Changelog 缺失或格式异常:先修复版本段落格式,再执行打标。
- 过滤后暂存内容为空:停止并说明无可发布改动。