specsfy-specialist-versioning

版本管理

适用场景

• 准备发布、用于部署的镜像、Git 标签或环境晋级时，由 $specsfy-specialist-deploy 调用。
• 对于完整的发布或部署请求，准备并核对版本后，将协调工作交回 $specsfy-specialist-deploy。
• 未经明确授权，不得发布镜像、标签、GitHub Release，也不得执行部署。本地准备可以创建或更新 SEMVER。

流程

1. 定位项目根目录，并读取 SEMVER、Git 标签、变更日志以及交付相关产物。
2. 仅当 SEMVER 不存在且已确认初始版本时，才创建 SEMVER。
3. 将变更归类为 patch、minor 或 major，说明影响，并在写入前提出下一个版本。
4. 在获准的准备过程中更新 SEMVER，并将相同的值传递到属于该交付的元数据、镜像和清单中。
5. 执行测试，并核对版本是否高于上一次发布的版本。
6. 获准发布时，先发布不可变产物。只有在产物可用后，才能创建 Git 标签和 GitHub Release。
7. 提供版本、摘要、提交、涉及的环境以及回滚命令。

标准

• 在根目录中保留 SEMVER，其中只包含一个稳定版本号 MAJOR.MINOR.PATCH，并以换行符结尾。
• 兼容性修复使用 patch，兼容性功能使用 minor，不兼容变更使用 major。
• 将 SEMVER 视为准备中版本的来源。Git 标签、OCI 注释、变更日志和堆栈引用都必须使用相同的值。
• 使用 SemVer 标签和提交标识发布镜像，记录摘要；平台支持时，按摘要进行部署。
• 推送前确认不可变标签是否已存在。绝不替换已发布的镜像或标签。
• 使用本地实用程序执行确定性操作：

node scripts/semver.mjs current --project .
node scripts/semver.mjs bump patch --project .
node scripts/semver.mjs verify 1.4.1 --project .
node scripts/semver.mjs docker-tag registry.example/app --project .
node scripts/semver.mjs verify-docker-tag registry.example/app:1.4.1 --project .

安装 skill 时，请调整第一个路径，使其指向 Agent 的 skills 库中的 specsfy-specialist-versioning/scripts/semver.mjs。

反模式

• 使用 latest 作为交付标识。
• 镜像已使用其他值构建后，再更改 SEMVER。
• 尚未确认镜像已存在于 registry 中，就创建 Git 标签。
• 为修正一次发布而重新构建相同版本号。应准备一个新的版本增量。
• 将本地准备与默认的发布或更改远程环境授权混为一谈。

验证

• 执行 current 和 verify，确认 SEMVER 的内容。
• 使用 docker-tag 生成 Docker 标签，并在构建、推送或部署前执行 verify-docker-tag；与 SEMVER 不同的标签会中断流程。
• 将版本与上一个 Git 标签比较，并拒绝相同或更低的值。
• 比较 SEMVER、镜像标签、OCI 注释、变更日志和部署清单。
• 创建 Git 标签前，确认已发布的摘要。
• 确认回滚指向已可用的版本和摘要。

相关 Skills

• $specsfy-specialist-deploy 是唯一负责协调完整发布或部署流程的 skill。
• $specsfy-specialist-docker 构建并发布由此处准备的版本标识的镜像。
• $specsfy-specialist-docker-swarm 将此 skill 核对过的镜像和摘要部署到集群。
• $specsfy-specialist-ansible 传输已版本化的清单，并在主机上执行预检。
• $specsfy-specialist-delivery-engineering 协调测试、晋级、标签和 GitHub Release。

阅读 references/standards.md，了解 SemVer、Git、OCI 镜像之间的对应关系以及发布顺序。