用途
该文档描述 SlackCLI 的完整发布流程，把一次发布拆成两步，并按顺序执行：
- 向 main 提交一个 PR，修改 package.json 版本号并整理 CHANGELOG。这一步可逆。
- 向合并后的提交推送附注标签。这一步不可逆且对外可见：release.yml 会构建并发布公开二进制文件，并强制更新 shaharia-lab/homebrew-tap 上的 Homebrew tap。
未经人工明确确认，不得执行第二步。
硬性约束
- 标签与 package.json 版本不一致时 release.yml 会失败（#82）。版本号变更必须先合入 main 再推标签；事后修复意味着在 main 上再升一次版本，然后删除并重新推送标签。
- main 要求签名提交，且无绕过者——未签名提交会使 PR 对任何人（包括管理员）都无法合并。需确认发布提交带有签名。
- 仓库在 CLAUDE.md 中的约定同样适用于发布 PR：PR 打开前需要有一个带 ready-for-pr 标签的关联 GitHub issue，pr-linked-issue.yml 会把该关联作为必需检查强制执行。
- main 要求一次批准评审，且代理不能批准自己的 PR。因此即使所有检查通过，gh pr merge 仍会报告 BLOCKED / REVIEW_REQUIRED。解除阻塞由维护者决定，方式有两种：一次评审，或明确指示使用 --admin 合并。不得自行选择 --admin；应说明阻塞情况，让维护者决定。dismiss_stale_reviews_on_push 已开启，批准后的任何推送都会丢弃批准，因此请求评审前应先把分支定稿。
- 提交前钩子会阻止直接提交到 main，因此始终在分支上操作。
- 合并的 PR 不保证有 CHANGELOG 条目。需自行将提交与 [Unreleased] 对照——#96 中的 mrkdwn 修复合并时没有条目，到 v0.9.0 才补上。
- 非交互式 shell 中 bun 可能不在 PATH 上；若找不到 bun，使用 export PATH="$HOME/.bun/bin:$PATH"。
操作步骤
1. 查看待发布内容
git describe --tags --abbrev=0 git log <last-tag>..HEAD --pretty=format:'%h %ad %s' --date=short git diff <last-tag>..HEAD --stat
把面向用户的提交（feat、fix、perf 及任何改变 CLI 行为的提交）与不对外发布的提交（ci、chore、docs、依赖升级）区分开。只有第一类才构成发布理由或决定版本号。阅读面向用户提交的正文，其中包含 changelog 需要的 WHAT/WHY：
git show <sha> --pretty=format:'%B' --stat
2. 推荐版本号
遵循仓库已采用的 pre-1.0 语义化版本约定：
- 新命令、新标志、新接受的输入格式 → minor（0.8.0 → 0.9.0）
- 仅缺陷修复 → patch（0.8.0 → 0.8.1）
行动前先说明推荐及理由。仅改变原本已损坏输出的行为变更仍属修复，不是破坏性变更。
3. 核对 CHANGELOG
将第 1 步的面向用户提交与 [Unreleased] 区段对照。已发布但未记录的，现在按周边文件的行文风格补写条目：改了什么、用户为何关心。有意为之的行为变更需明确说明。
4. 创建发布 issue
PR 之前必需，沿用仓库的 WHAT / WHY / HOW 结构（参见 #101、#111）：
- WHAT — 发布 vX.Y.Z，将 package.json 从 A 升到 B。
- WHY — main 上尚未进入已发布构建的面向用户变更，各附 issue/PR 编号；SemVer 理由；release.yml 的标签/版本约束（#82）。
- HOW — 升版本、整理 changelog、合并、推送附注标签。
可选加入 Not included 一节，列出有意推迟的开放 ready-for-pr issue，使省略显得是有意决定。
gh issue create --title "Release vX.Y.Z" --body-file <file> --label ready-for-pr
5. 准备分支
git checkout -b chore/release-vX.Y.Z
- package.json：升级版本号。
- CHANGELOG.md：在 ## [Unreleased] 下方插入 ## [X.Y.Z] - YYYY-MM-DD 标题，保留空的 [Unreleased]，使现有条目归入新版本下。
提交前验证：
bun run type-check bun test
两者都必须通过。提交正文包含 Closes #<issue>，然后确认签名存在：
git cat-file -p HEAD | grep -q gpgsig && echo signed
git log --show-signature 可能仅因本地未设置 gpg.ssh.allowedSignersFile 而报告签名未验证；这是本地验证缺口，并非未签名提交。以 GitHub 为准——PR 上的 check-signatures 报告真实结果。
6. 创建 PR
gh pr create --base main --head chore/release-vX.Y.Z --title "chore: release vX.Y.Z" --body-file <file>
PR 正文应包含：摘要与 release.yml 约束、Included since 列出面向用户的变更、本 PR 的改动、检查结果、合并后的发布步骤，以及 Closes #<issue>。
然后等待检查：gh pr checks <pr>。关联的开放 issue、check-signatures、test、unit-tests 和 integration-tests 必须通过。
7. 打标签前的确认关卡
停在这里，请人工确认合并和打标签。此前所有步骤可逆；标签不可逆——它会发布公开二进制并改写 Homebrew formula。
无论是否人工确认，维护者都得解除 PR 阻塞——分支规则集要求一次 PR 作者本人无法提供的评审——因此该确认关卡不增加额外成本。
维护者批准或明确要求 --admin 后：
gh pr merge <pr> --squash # 仅在明确指示时添加 --admin git checkout main && git pull git tag -a vX.Y.Z -m "Release vX.Y.Z" git push origin vX.Y.Z
标签必须指向已合并的版本提交。若标签所指的是 package.json 仍为旧版本的提交，verify-version 会立即失败。
8. 核验发布结果
gh run list --workflow=release.yml --limit 3 gh release view vX.Y.Z
确认五个二进制文件加 checksums.txt 均已附上（slackcli-linux、slackcli-linux-arm64、slackcli-macos、slackcli-macos-arm64、slackcli-windows.exe），且 update-homebrew 成功。然后检查最后一个作业 announce-discord：它会把发布公告发到 Shaharia Lab Discord，且为非阻塞，因此即使失败整个运行仍显示绿色——需读取该作业自身结果（gh run view <run-id> --json jobs --jq '.jobs[] | "(.name): (.conclusion) ((.databaseId))"'）。若失败，单独重跑该作业（gh run rerun --job <databaseId>，即上述查询打印的 id），或告知维护者公告缺失；对预发布标签，该作业按设计跳过。最后报告发布 URL。
适用场景与限制
适用于维护者或代理按仓库约定完成 SlackCLI 的正式发布，包括版本决策、变更记录补齐、PR/issue 流程与发布后核验。限制在于：打标签属不可逆对外操作，必须人工确认；合并需维护者解除评审阻塞；提交必须签名；发布产物与 Homebrew 更新由 release.yml 控制，标签版本必须与 package.json 一致。