版本号与 tag

确定权威版本来源

按项目实际构建链路寻找版本来源，不要遍历到一个看起来像版本号的字符串就修改。优先级：

项目发布文档或 .release-policy.yaml 明确声明的文件。
构建、打包或运行入口直接读取的清单，例如 VERSION、package.json、 pyproject.toml、Cargo.toml 或语言工具链的版本配置。
由权威文件生成的镜像文件、锁文件或发布元数据。
最近稳定 tag，只用于验证当前版本和发布历史。

记录每个权威文件的当前值和更新方式。多个权威来源不一致时停止，不要选择修改时间最新的文件，也不要只改其中一个。

配置声明的版本文件必须使用仓库相对路径。拒绝绝对路径、.. 和解析后逃出目标 worktree 的 symlink；修改前确认规范化后的准确路径。不要用 glob 或模糊搜索结果执行批量替换。

选择目标版本

项目已有 CalVer、单调构建号、独立包版本或自定义方案时继续使用，不要迁移到 SemVer。项目没有规则且只有一个协调版本时使用 SemVer：

不兼容的公开 API 或行为变化增加 major。
向后兼容的新功能增加 minor。
向后兼容的修复增加 patch。

根据实际兼容性判断，不要只凭 commit 前缀自动升级。项目明确采用 Conventional Commits 或已有版本工具时，可以把它们的结果作为项目规则。破坏性影响无法确定时给出建议并请用户确定准确版本。

预发布版本沿用项目格式；没有格式时使用 -alpha.N、-beta.N 或 -rc.N。正式 tag 默认不加入 build metadata。不要从带 build metadata 的 tag 推断兼容性顺序。

独立多包版本、多个维护分支和 release train 不属于默认单版本流程。无法确定一个目标版本时停止并说明需要增加包或发布线维度。

规范化与渲染

内部始终分别记录规范版本、分支名和 tag 名。默认 SemVer 的规范版本不含 v，例如用户输入 v1.6.0 时规范化为 1.6.0；版本文件写入 1.6.0，再将它代入 release/v{version} 和 v{version}。不要把完整 tag 名直接代入 {version}。

项目采用自定义前缀或非 SemVer 时，以项目版本来源定义规范值，以 branch/tag pattern 定义展示形式。规范化结果无法唯一确定时停止并让用户确认。

同步版本

在发布分支中一次性更新所有权威版本来源、生成文件和项目要求的 CHANGELOG。运行项目自己的版本更新工具时，先检查它会修改哪些文件，避免隐式发布、提交或上传。

提交前确认：

所有权威来源都是目标版本。
生成文件与来源一致。
CHANGELOG 或发布说明描述的是本次实际变更。
项目构建和测试读取到了新版本。

验证 merged commit

合并后以代码托管平台返回的 merged commit 为准。获取远端 base 后，确认该 commit 可从远端 base 到达，并直接读取该 commit 中的版本文件。不要用仍停留在 feature worktree 中的文件证明已合并版本。

正式 tag 必须满足：

tag 名按项目格式由目标版本唯一生成。
远端没有同名 tag，或同名 tag 已经准确指向本次 commit。
annotated tag 显式指向 merged commit。
项目要求签名时，push 前已成功创建 signed tag，并在本地验证签名通过；不可用或失败时停止，不得改用 unsigned tag。
推送后从远端重新读取，并将 annotated tag 解引用到 commit。

展开 tag pattern 后用 git check-ref-format refs/tags/<tag> 校验。把 tag 和 commit 作为独立 argv 传递，不拼接 shell 字符串。

tag 已在远端指向其他 commit 时停止。不要 force push、删除或移动已发布 tag；由维护者决定撤销发布或创建新的修订版本。

3.9 KiB Raw Blame History