80 lines
3.9 KiB
Markdown
80 lines
3.9 KiB
Markdown
# 版本号与 tag
|
|
|
|
## 确定权威版本来源
|
|
|
|
按项目实际构建链路寻找版本来源，不要遍历到一个看起来像版本号的字符串就修改。优先级：
|
|
|
|
1. 项目发布文档或 `.release-policy.yaml` 明确声明的文件。
|
|
2. 构建、打包或运行入口直接读取的清单，例如 `VERSION`、`package.json`、
|
|
`pyproject.toml`、`Cargo.toml` 或语言工具链的版本配置。
|
|
3. 由权威文件生成的镜像文件、锁文件或发布元数据。
|
|
4. 最近稳定 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；由维护者
|
|
决定撤销发布或创建新的修订版本。
|