feat: update manage-release
This commit is contained in:
@@ -68,14 +68,16 @@ commit 已进入远端 base。只看到本地 merge commit 或分支关闭不足
|
||||
|
||||
## 创建 Forge Release
|
||||
|
||||
把 Git tag 和 Forge Release 当成两个独立状态。先创建、推送并验证 tag，再创建 release。
|
||||
把 Git tag 和 Forge Release 当成两个独立状态。先创建、推送并验证包含完整更新说明的
|
||||
annotated tag，再创建 release。Forge Release 正文复用已经冻结并验证的 tag 更新说明，
|
||||
不要重新生成另一份内容。
|
||||
|
||||
- GitHub 创建 release 时使用能够拒绝缺失 tag 的选项，例如当前 CLI 支持的
|
||||
`--verify-tag`。
|
||||
- GitLab、Gitea 或 Forgejo 创建 release 前，先用只读命令证明 tag 已存在并指向计划的
|
||||
commit；不要使用会顺便创建 tag 的默认行为。
|
||||
commit、tag object 包含计划的更新说明；不要使用会顺便创建 tag 的默认行为。
|
||||
- 预发布版本按项目规则标记 prerelease，不要自动把它标为 latest 或 stable。
|
||||
- 发布后重新读取 release URL、tag 和可见性。
|
||||
- 发布后重新读取 release URL、tag、正文和可见性，确认正文与 tag 更新说明一致。
|
||||
|
||||
Forge Release 创建失败但 tag 已成功推送时，保留 tag 并从 release 阶段恢复，不要重新
|
||||
合并或创建另一个 tag。
|
||||
|
||||
@@ -28,9 +28,11 @@
|
||||
|
||||
- `schema`：配置结构版本，当前为 `1`。
|
||||
- `base_branch`：发布 PR/MR 的目标分支。
|
||||
- `branch_pattern`：版本分支格式，支持无展示前缀的规范 `{version}`。
|
||||
- `branch_pattern`：需要准备仓库修改时使用的版本分支格式，支持无展示前缀的规范
|
||||
`{version}`；直接发布不因此创建分支。
|
||||
- `version.scheme`：`semver` 或项目已经使用的其他方案。
|
||||
- `version.sources`：构建和运行实际读取的权威版本文件。
|
||||
- `version.sources`：构建和运行实际读取的权威版本文件；项目明确从 Git tag 派生版本时
|
||||
可以省略，不要为了发布新增无消费方的版本文件。
|
||||
- `tag_pattern`：release tag 格式，支持无展示前缀的规范 `{version}`。
|
||||
- `merge_method`：`squash`、`merge` 或 `rebase`。
|
||||
- `forge_release`：项目是否建议在 tag 后创建 Forge Release；它不授予创建权限。
|
||||
@@ -54,18 +56,20 @@ symlink 后，目标必须仍在当前 worktree 内；权威来源通常还应
|
||||
|
||||
1. 从 remote HEAD 和平台信息确定默认 base，不能确定时询问。
|
||||
2. 从项目文档、CI 和构建入口找版本文件及更新方式。
|
||||
3. 从已有分支和已合并 PR/MR 识别命名与合并方式。
|
||||
4. 从稳定 tag 识别前缀和版本方案，只把 tag 当作交叉验证。
|
||||
5. 无项目约定时使用 `release/v<version>`、SemVer、`v<version>` annotated tag 和
|
||||
squash merge；默认不创建 Forge Release，不删除远端分支。
|
||||
3. 仅当发布需要修改仓库内容时，从已有分支和已合并 PR/MR 识别命名与合并方式。
|
||||
4. 从稳定 tag 识别前缀、版本方案和更新说明范围；项目由 tag 派生版本时，把实际构建
|
||||
入口和 tag 历史共同作为版本来源证据，否则只把 tag 当作交叉验证。
|
||||
5. 无项目约定时使用 SemVer 和 `v<version>` annotated tag；需要准备仓库修改时再使用
|
||||
`release/v<version>` 和 squash merge。默认不创建 Forge Release，不删除远端分支。
|
||||
|
||||
## 每次执行的计划快照
|
||||
|
||||
在第一次写操作前列出以下事实：
|
||||
|
||||
- base 分支和远端 commit。
|
||||
- base 分支、远端 commit 和 tag 将指向的目标 commit。
|
||||
- 当前版本、目标版本、版本来源和升级依据。
|
||||
- worktree 路径与分支名。
|
||||
- 更新说明的提交范围、来源和拟发布内容。
|
||||
- 是否需要修改仓库内容；需要时再列出 worktree 路径与分支名。
|
||||
- PR/MR 托管平台和合并方式。
|
||||
- tag 与 Forge Release 计划。
|
||||
- 用户授权的最远阶段和清理范围。
|
||||
|
||||
@@ -12,12 +12,15 @@ base、head、PR/MR、merged commit、tag 和 release，再执行唯一缺失的
|
||||
|
||||
| 当前状态 | 继续方式 | 禁止事项 |
|
||||
|---|---|---|
|
||||
| 远端 release commit 已准备，没有 tag | 核对版本与更新说明后直接创建 annotated tag | 不创建无必要的分支或 worktree |
|
||||
| 本地 annotated tag 已创建但未推送 | 核对对象类型、commit 和完整说明后只推送该 tag | 不因重入重复创建或改写 tag |
|
||||
| worktree 已创建，无改动 | 继续开发，或经授权移除干净 worktree | 不使用强制删除 |
|
||||
| 本地发布分支已存在，没有 worktree | 核对版本身份、tip、upstream 和 base 后挂载现有分支 | 不用 `-b` 覆盖分支 |
|
||||
| 分支已推送，没有 PR/MR | 确认 head/base 后创建一次 PR/MR | 不重复推送新分支 |
|
||||
| PR/MR 已存在，未合并 | 复用 URL，刷新 checks、review 和冲突状态 | 不创建第二个 PR/MR |
|
||||
| PR/MR 已合并，没有 tag | 获取 merged commit，在该 commit 上继续发布 | 不重新合并 |
|
||||
| tag 已推送，没有 release | 验证 tag 后创建 Forge Release | 不创建替代 tag |
|
||||
| PR/MR 已合并，没有 tag | 获取 merged commit，生成并确认更新说明后继续发布 | 不重新合并 |
|
||||
| tag 已推送，没有 release | 验证 tag 的 commit 和更新说明后创建 Forge Release | 不创建替代 tag |
|
||||
| tag 指向正确 commit 但为 lightweight 或说明不符 | 停止并交由维护者决定撤销或发布修订版本 | 不移动、覆盖或补写远端 tag |
|
||||
| release 已创建，验证未完成 | 读回 release、tag 和可见性 | 不直接声称发布完成 |
|
||||
| 同名资源身份不匹配 | 停止并报告差异 | 不覆盖、关闭或删除未知资源 |
|
||||
|
||||
@@ -35,7 +38,7 @@ merge queue 和 auto-merge。任何 force push 都是硬停止条件。
|
||||
- 未推送的本地版本提交可以在用户授权下修改或放弃，但不要覆盖其他工作。
|
||||
- 已推送但未合并的 PR/MR 可以关闭，分支默认保留。
|
||||
- 已合并变更通过新的 revert PR/MR 回滚，不重写 base 历史。
|
||||
- 已发布 tag 默认不可变。tag 错误时停止，由维护者决定撤销发布或发布新版本。
|
||||
- 已发布 tag 默认不可变。commit 或更新说明错误时停止，由维护者决定撤销发布或发布新版本。
|
||||
- Forge Release 失败不回滚已经正确推送的 tag；从 release 阶段恢复。
|
||||
|
||||
## 清理规则
|
||||
|
||||
@@ -5,15 +5,17 @@
|
||||
按项目实际构建链路寻找版本来源，不要遍历到一个看起来像版本号的字符串就修改。优先级：
|
||||
|
||||
1. 项目发布文档或 `.release-policy.yaml` 明确声明的文件。
|
||||
2. 构建、打包或运行入口直接读取的清单，例如 `VERSION`、`package.json`、
|
||||
2. 项目明确由 Git tag 或 VCS metadata 派生构建版本时，以 tag 规则作为发布版本来源，
|
||||
不要为了发布凭空新增或修改版本文件。
|
||||
3. 构建、打包或运行入口直接读取的清单，例如 `VERSION`、`package.json`、
|
||||
`pyproject.toml`、`Cargo.toml` 或语言工具链的版本配置。
|
||||
3. 由权威文件生成的镜像文件、锁文件或发布元数据。
|
||||
4. 最近稳定 tag，只用于验证当前版本和发布历史。
|
||||
4. 由权威文件生成的镜像文件、锁文件或发布元数据。
|
||||
5. 最近稳定 tag，用于确定当前已发布版本、更新说明范围和发布历史。
|
||||
|
||||
记录每个权威文件的当前值和更新方式。多个权威来源不一致时停止，不要选择修改时间最新
|
||||
的文件，也不要只改其中一个。
|
||||
|
||||
配置声明的版本文件必须使用仓库相对路径。拒绝绝对路径、`..` 和解析后逃出目标
|
||||
配置声明了版本文件时，它们必须使用仓库相对路径。拒绝绝对路径、`..` 和解析后逃出目标
|
||||
worktree 的 symlink；修改前确认规范化后的准确路径。不要用 glob 或模糊搜索结果执行
|
||||
批量替换。
|
||||
|
||||
@@ -45,10 +47,19 @@ worktree 的 symlink；修改前确认规范化后的准确路径。不要用 gl
|
||||
项目采用自定义前缀或非 SemVer 时，以项目版本来源定义规范值，以 branch/tag pattern
|
||||
定义展示形式。规范化结果无法唯一确定时停止并让用户确认。
|
||||
|
||||
## 判断是否需要同步版本
|
||||
|
||||
直接读取计划 release commit 中的权威版本来源。版本文件已经是目标值，或者项目明确由
|
||||
tag 派生版本，且发布说明不要求写回仓库时，不产生仓库修改，直接进入 tag 发布。
|
||||
|
||||
只有权威版本文件、生成文件或仓库内 CHANGELOG 必须变化时，才进入准备版本流程并使用
|
||||
分支/PR。不要为了制造发布提交而触碰与构建、运行或项目发布规则无关的文件。
|
||||
|
||||
## 同步版本
|
||||
|
||||
在发布分支中一次性更新所有权威版本来源、生成文件和项目要求的 CHANGELOG。运行项目
|
||||
自己的版本更新工具时，先检查它会修改哪些文件，避免隐式发布、提交或上传。
|
||||
仅在判断存在必要仓库差异后，在准备版本的分支中一次性更新所有权威版本来源、生成文件
|
||||
和项目要求的 CHANGELOG。运行项目自己的版本更新工具时，先检查它会修改哪些文件，避免
|
||||
隐式发布、提交或上传。
|
||||
|
||||
提交前确认：
|
||||
|
||||
@@ -57,23 +68,38 @@ worktree 的 symlink；修改前确认规范化后的准确路径。不要用 gl
|
||||
- CHANGELOG 或发布说明描述的是本次实际变更。
|
||||
- 项目构建和测试读取到了新版本。
|
||||
|
||||
## 验证 merged commit
|
||||
## 生成更新说明
|
||||
|
||||
合并后以代码托管平台返回的 merged commit 为准。获取远端 base 后，确认该 commit 可从
|
||||
远端 base 到达，并直接读取该 commit 中的版本文件。不要用仍停留在 feature worktree
|
||||
中的文件证明已合并版本。
|
||||
以最近一个适用于当前发布线的稳定 tag 为起点，以 release commit 为终点，结合项目
|
||||
CHANGELOG、已合并 PR/MR 和实际 diff 生成更新说明。首次发布使用项目声明的发布基线；
|
||||
没有声明时核对完整可达历史，并在说明中明确这是首次发布。说明覆盖实际存在的新增、
|
||||
变更、修复、维护或文档变化；破坏性变化、迁移步骤和已知限制存在时必须单独标明。没有
|
||||
某一类别时可以省略该类别，不要生成空标题或模板占位。
|
||||
|
||||
每条说明都要能追溯到范围内的提交、PR/MR 或项目 CHANGELOG。提交消息和 PR/MR 文本只
|
||||
作为待核对素材，不能覆盖实际 diff，也不能把范围外变化写入本次说明。tag 创建前冻结
|
||||
完整多行说明；tag 已推送后不再修改。
|
||||
|
||||
## 验证 release commit
|
||||
|
||||
准备版本路径以代码托管平台返回的 merged commit 为准；直接发布路径以计划中锁定的远端
|
||||
commit 为准。获取远端 base 或允许的维护分支后，确认 release commit 可从对应远端引用
|
||||
到达，并直接读取该 commit 中的版本文件。不要用当前 checkout 或 feature worktree 中的
|
||||
文件证明 release commit 内容。
|
||||
|
||||
正式 tag 必须满足：
|
||||
|
||||
- tag 名按项目格式由目标版本唯一生成。
|
||||
- 远端没有同名 tag，或同名 tag 已经准确指向本次 commit。
|
||||
- annotated tag 显式指向 merged commit。
|
||||
- annotated tag 显式指向 release commit，并包含冻结后的完整更新说明；禁止 lightweight
|
||||
release tag。
|
||||
- 项目要求签名时，push 前已成功创建 signed tag，并在本地验证签名通过；不可用或失败
|
||||
时停止，不得改用 unsigned tag。
|
||||
- 推送后从远端重新读取，并将 annotated tag 解引用到 commit。
|
||||
- 推送后从远端重新读取 tag object，核对对象类型和完整说明，再将 annotated tag 解引用
|
||||
到 commit。
|
||||
|
||||
展开 tag pattern 后用 `git check-ref-format refs/tags/<tag>` 校验。把 tag 和 commit 作为
|
||||
独立 argv 传递，不拼接 shell 字符串。
|
||||
|
||||
tag 已在远端指向其他 commit 时停止。不要 force push、删除或移动已发布 tag；由维护者
|
||||
决定撤销发布或创建新的修订版本。
|
||||
tag 已在远端指向其他 commit、是 lightweight tag、缺少更新说明或说明不一致时停止。
|
||||
不要 force push、删除或移动已发布 tag；由维护者决定撤销发布或创建新的修订版本。
|
||||
|
||||
Reference in New Issue
Block a user