git-auto-release

name	git-auto-release
description	在需要根据本地改动自动完成提交、推送和语义化打标时使用，尤其适用于发布流程要求 CHANGELOG 存在对应版本条目的场景。

Git 自动发布

概述

该技能用于规范一套完整发布流程：分析当前改动、生成合适提交、推送分支更新、计算下一个语义化版本标签、更新变更日志条目并推送标签。

它适用于通过 v* 标签触发自动发布、且要求 CHANGELOG.md 中必须包含对应 [x.y.z] 版本段落的仓库。

何时使用

• 需要一次性完成提交 + 推送 + 打标签。
• 希望标签版本由改动影响自动推导，而不是手工指定。
• 发布流水线会校验 CHANGELOG.md 是否包含对应 [version] 条目。

以下场景不建议使用：

• 分支策略禁止直接推送。
• 用户明确要求手动指定版本号。

输入项

• 目标分支（默认：当前分支）。
• 远程名称（默认：origin）。
• 可选的发布说明关注点（用于优化 changelog 条目）。

工作流

1. 校验仓库状态。
2. 暂存相关文件。
3. 推断提交类型并生成提交信息。
4. 基于最近 vX.Y.Z 标签计算下一版本。
5. 确保 CHANGELOG.md 存在 [newVersion] 条目。
6. 将代码改动与 changelog 一起提交。
7. 推送分支。
8. 创建并推送标签。
9. 校验本地与远程结果。

步骤细则

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]*"

版本基线规则：

• 如果找不到匹配标签，下一个版本为 0.0.1。

版本提升规则：

• 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 缺失或格式异常：先修复版本段落格式，再执行打标。
• 过滤后暂存内容为空：停止并说明无可发布改动。