项目使用 release-please 且发布需手动…

适用于 release-please 管理版本、GitHub Actions 手动触发的发布流程：合并 release PR 后再次 dispatch，生成 tag、Release、二进制、签名、SBOM 和 Homebrew cask。

适用场景

解决思路

1. 通过 `.github/workflows/release.yml` 的 `workflow_dispatch` 触发发布流程：在 Actions 页面点击 Run workflow，或运行 `gh workflow run release.yml`；普通合并到 `main` 不会发布。
2. 不要手动改版本号、不要编辑 `CHANGELOG.md`、不要手动推 tag；版本和 release notes 由 release-please 根据上次发布以来的 Conventional Commits 计算。
3. 一次完整发布需要两次 dispatch，并在两次之间合并 release PR。
4. Dispatch #1：运行 `gh workflow run release.yml`，让 `release-please` job 检查上次发布以来的 conventional commits，并打开/更新 release PR，标题类似 `chore(main): release 0.31.0`。
5. Dispatch #1 产生的 release PR 会：更新 `.release-please-manifest.json`；更新 `pkg/version/version.go` 中的 fallback version（通过 `// x-release-please-version` 注解）；在 PR body 中包含待发布 release notes。
6. 在确认版本和 notes 符合预期后，合并 release PR。
7. Dispatch #2：再次运行 `gh workflow run release.yml`，让 release-please 检测已合并的 release PR，创建 git tag（`vX.Y.Z`）和 GitHub Release（带生成的 notes）。
8. 确保 `release-please` job 输出 `release_created == true`，以触发 `goreleaser` job。
9. `goreleaser` job 会构建跨平台二进制、用 cosign 签名 checksums、用 syft 生成 SBOM，并把所有内容附加到 release（不覆盖 notes，因为配置了 `release.mode: keep-existing`）。
10. `goreleaser` job 会把更新后的 Homebrew cask 推送到 `dynatrace-oss/homebrew-tap`。
11. 不要忘记 Dispatch #2：只合并 release PR 不会发布任何东西，因为 workflow 只在手动 dispatch 时运行。
12. 不要创建或编辑 `CHANGELOG.md`；仓库中设计上不存在该文件，GitHub Release 是权威 changelog（`release-please-config.json` 中设置 `skip-changelog: true`）。
13. 版本 bump 由 commit type 决定：`feat:` 为 MINOR（pre-1.0 示例 0.30.3 → 0.31.0）。
14. `fix:` / `perf:` 为 PATCH（示例 0.30.3 → 0.30.4）。
15. `feat!:` / `fix!:` 或 `BREAKING CHANGE:` footer 为 MINOR（pre-1.0，示例 0.30.3 → 0.31.0）。
16. `docs:` / `test:` / `chore:` / `ci:` / `refactor:` 单独不会触发 release。
17. 通过写好 Conventional Commits 来控制版本（参见 `CONTRIBUTING.md`）；PR 使用 squash merge，因此 PR 标题会成为与发布相关的 commit。
18. 切割 release 步骤 1：运行 `gh workflow run release.yml`，然后运行 `gh run watch`，等待 release-please 运行结束，以从上次发布以来的 commits 构建/更新 release PR。
19. 切割 release 步骤 2：运行 `gh pr list --search "chore(main): release in:title" --state open` 找到 release PR，检查提议的版本和 notes，然后运行 `gh pr merge <number> --squash` 合并。
20. 切割 release 步骤 3：再次运行 `gh workflow run release.yml`，然后运行 `gh run watch`，创建 tag + GitHub Release 并发布制品。
21. 切割 release 步骤 4：运行 `gh release view "$(gh release list --limit 1 --json tagName -q '.[0].tagName')"` 确认发布。
22. 确认 tag、GitHub Release、binaries、signatures、SBOMs 和 Homebrew cask 都由第二次 dispatch 生成。
23. 可选润色 release notes：release-please 生成的 notes 默认按 commit type 分组并带 PR 链接；如需更丰富的文案，在 GitHub Release 发布后运行 `gh release edit vX.Y.Z --notes-file notes.md` 编辑；GoReleaser 使用 `keep-existing`，不会覆盖你的编辑。
24. 排障：没有出现 release PR 时，先确认是否运行了 `gh workflow run release.yml`；它不会在 merge 时运行。如果已运行仍没有 PR，检查上次发布以来是否有可发布 commits（只有 `docs`/`chore`/`test` 等不行），或 commit 是否为有效 Conventional Commit；运行 `gh run list --workflow=release.yml` 检查。
25. 排障：已合并 release PR 但没有任何发布是预期行为；需要第二次 dispatch workflow，让 release-please 创建 tag/Release 并让 GoReleaser 运行。
26. 排障：版本 bump 不对通常由 commit types 导致；要强制指定 bump，在 `main` 的某个 commit 中使用 `Release-As: x.y.z` footer。
27. 排障：Release 已创建但没有 binaries 时，检查 release workflow run 中的 `goreleaser` job；`release-please` job 必须输出 `release_created: true` 它才会运行。
28. 排障：Homebrew 没有更新时，检查 `HOMEBREW_TAP_APP_ID` / `HOMEBREW_TAP_APP_PRIVATE_KEY` secrets 和 GoReleaser step logs；`skip_upload: auto` 会故意跳过 pre-release tags。
29. Checklist 1：确保所有预期变更已作为 conventional commits 合并到 `main`。
30. Checklist 2：Dispatch #1 运行 `gh workflow run release.yml` → release PR 已创建/更新。
31. Checklist 3：确认打开的 release PR 反映预期版本和 notes。
32. Checklist 4：合并 release PR（squash）。
33. Checklist 5：Dispatch #2 运行 `gh workflow run release.yml` → tag + Release 已创建。
34. Checklist 6：`release.yml` run 在 `release-please` 和 `goreleaser` 两个 jobs 都为绿色。
35. Checklist 7：GitHub Release 显示 binaries、checksums、signatures、SBOMs。
36. Checklist 8：可选，通过 `gh release edit` 润色 release notes。

适用边界 · 注意事项

• 不适用于未使用 release-please 或未采用 GitHub Actions `workflow_dispatch` 手动触发的项目。
• 不适用于期望普通合并到 `main` 就自动发布，或必须维护 `CHANGELOG.md` 的项目。
• 不适用于没有 `gh` CLI、GoReleaser、cosign、syft 或 Homebrew tap secrets 的环境。