123 lines
5.6 KiB
Markdown
123 lines
5.6 KiB
Markdown
# manage-release
|
|
|
|
`manage-release` 帮助 Agent 发布已经准备好的 Git commit，也能在发布前确有必要时管理
|
|
版本文件、worktree、分支、PR/MR 和合并。普通发布优先走“更新说明 + annotated tag”的
|
|
短路径；只有发布要求修改仓库内容时，才进入准备版本的分支流程。
|
|
|
|
## 使用前准备
|
|
|
|
- 项目已经是 Git 仓库，并配置了可访问的远端。
|
|
- 项目已有版本来源或 tag 发布约定；没有时可以让 Agent 先给出版本建议。
|
|
- 创建或合并 PR/MR、创建 Forge Release 时，准备好 GitHub、GitLab、Gitea 或 Forgejo
|
|
对应的已认证 CLI。只发布 Git tag 时不要求 Forge CLI，但 Git remote 必须可读写。
|
|
- 请求里写清目标版本、基线分支，以及允许执行到哪一步。没有明确授权的远端写操作
|
|
不会执行。
|
|
|
|
## 常见用法
|
|
|
|
### 确定下一个版本号
|
|
|
|
```text
|
|
使用 manage-release 检查当前版本和这次改动，建议下一个版本号。只分析，不修改文件。
|
|
```
|
|
|
|
适合还没决定该发 patch、minor 还是 major 时使用。Agent 会读取项目版本规则、现有 tag
|
|
和实际改动，给出建议及依据。
|
|
|
|
### 开始开发新版本
|
|
|
|
```text
|
|
使用 manage-release，从 main 为 1.6.0 创建独立 worktree 和分支。先不要 push，也不要创建 PR。
|
|
```
|
|
|
|
Agent 会检查已有 worktree、分支和 tag，确认没有冲突后准备开发目录。这个请求只授权
|
|
本地操作。
|
|
|
|
### 把开发分支提交为 PR
|
|
|
|
```text
|
|
使用 manage-release 检查当前分支，更新版本号和 CHANGELOG，运行项目测试，然后 push 并创建指向 main 的 PR。不要合并。
|
|
```
|
|
|
|
适合开发已经完成，只需要整理版本信息并送审。Agent 会停在 PR 创建成功的位置，返回
|
|
PR 地址、测试结果和待处理项。
|
|
|
|
### 合并通过检查的 PR
|
|
|
|
```text
|
|
使用 manage-release 检查当前 PR。如果 CI、review 和冲突检查都通过，就按项目规则合并；不要打 tag。
|
|
```
|
|
|
|
Agent 只会在仓库要求全部满足后合并，不会使用管理员权限绕过保护规则。合并完成后会
|
|
返回准确的 merged commit。
|
|
|
|
### 为已合并版本发布 tag
|
|
|
|
```text
|
|
使用 manage-release，为已经合并到 main 的 1.6.0 发布 v1.6.0 tag。根据 v1.5.0 到目标 commit 的实际变化生成更新说明，把说明写入 annotated tag，并验证远端 tag 的 commit 和说明。不要创建 Forge Release。
|
|
```
|
|
|
|
这是无需修改仓库文件时的默认短路径，适合依靠 Git tag 触发后续 CI 发布的项目。Agent
|
|
会分别验证目标 commit、更新说明和远端 tag，不会创建 worktree、发布分支或 PR，也不会
|
|
给未合并分支打正式 tag。
|
|
|
|
### 为已合并版本创建 Gitea Release
|
|
|
|
```text
|
|
使用 manage-release，发布已经合并到 main 的 1.6.0：生成更新说明，创建并验证附带说明的 v1.6.0 annotated tag，然后在 Gitea 创建使用同一份说明的 Release。
|
|
```
|
|
|
|
Agent 会先证明 tag 已存在、指向计划 commit 且包含更新说明，再创建 Gitea Release。
|
|
Release 创建失败时保留正确的 tag，从 Release 阶段恢复。
|
|
|
|
### 完成端到端发布
|
|
|
|
```text
|
|
使用 manage-release 完成 1.6.0 发布：从 main 创建 worktree 和分支，完成版本更新和验证，创建 PR，检查通过后合并，推送 v1.6.0 tag，并创建 Forge Release。
|
|
```
|
|
|
|
只有版本文件或仓库内 CHANGELOG 必须随发布修改时才使用这条长路径。tag 仍必须附带更新
|
|
说明，Forge Release 复用同一份说明。遇到 review 未通过、CI 失败、版本冲突或已有同名
|
|
tag 时，Agent 会停止并说明卡在哪一步，不会绕过检查继续发布。
|
|
|
|
### 发布紧急修复版本
|
|
|
|
```text
|
|
使用 manage-release 从 main 准备 1.6.1 hotfix。创建独立 worktree，完成修复后开 PR；检查通过就合并并发布 v1.6.1。
|
|
```
|
|
|
|
适合线上问题修复。Skill 仍走正常 PR 和保护分支流程，不会因为是 hotfix 就直接推送
|
|
main 或覆盖已有 tag。
|
|
|
|
### 从中断位置继续
|
|
|
|
```text
|
|
使用 manage-release 检查 v1.6.0 当前发布状态，从尚未完成的步骤继续。不要重复创建分支、PR、tag 或 release。
|
|
```
|
|
|
|
适合合并后打 tag 失败、tag 已推送但 release 未创建，或者 Agent 会话中断的情况。
|
|
Skill 会从 Git 和代码托管平台重新判断状态，再继续缺失的步骤。
|
|
|
|
## Agent 会做什么
|
|
|
|
Agent 会先发现项目自己的版本和发布规则、锁定远端目标 commit，再判断发布是否要求修改
|
|
仓库内容。不需要修改时直接生成更新说明并发布 annotated tag；需要修改时才准备分支，
|
|
并只在隔离用户工作确有必要时创建 worktree。它只执行请求中明确授权的阶段，并在合并、
|
|
tag 或 release 条件不满足时停止。
|
|
|
|
## 如何判断完成
|
|
|
|
- 只分析版本时，结果包含建议版本及依据。
|
|
- 创建开发环境时，结果包含 worktree 路径、分支和基线 commit。
|
|
- 创建或合并 PR/MR 时，结果包含 URL、检查状态和 merged commit。
|
|
- 发布 tag 时，远端 tag 解引用后的 commit 与目标 commit 一致，而且 tag object 包含经过
|
|
核对的更新说明。
|
|
- 创建 Forge Release 时，结果包含可访问的 release URL，正文与 tag 更新说明一致。
|
|
- 中途停止时，结果说明停在哪一步、为什么停止，以及下次如何继续。
|
|
|
|
## 不适用的场景
|
|
|
|
普通功能开发、普通 worktree 或 PR/MR 操作、代码审查、构建 Docker 镜像或上传 DEB 包
|
|
不需要触发 `manage-release`。只有任务明确涉及版本发布、发布分支、版本号、发布 PR/MR
|
|
或 release tag 时，才交给这个 Skill。
|