dtctl-release

用途

dtctl 的发布流程由 release-please 自动化，但不会在普通合并到 main 时自动发布，必须手动触发。本技能用于解释和操作这一发布流程，帮助用户完成从提交规范到最终发布产物的全过程。

主要能力

基于 Conventional Commits 自动计算版本号与发布说明，无需手动改版本、编辑 CHANGELOG.md 或手动打 tag。
通过两次手动触发 .github/workflows/release.yml（workflow_dispatch）完成完整发布，中间合并一次 release PR。
第一次触发：release-please 检查自上次发布以来的 conventional commits，创建或更新标题形如 chore(main): release 0.31.0 的 release PR，其中会更新 .release-please-manifest.json、更新 pkg/version/version.go 中的回退版本（通过 // x-release-please-version 注解），并在 PR 正文中包含待发布的发布说明。
第二次触发：release-please 检测到已合并的 release PR 后，创建 git tag（vX.Y.Z）和 GitHub Release（含生成的说明），并以 release_created == true 作为门控条件运行 goreleaser 任务，构建跨平台二进制、用 cosign 签名校验和、用 syft 生成 SBOM，将全部产物附加到 release（使用 release.mode: keep-existing，不覆盖说明），并把更新后的 Homebrew cask 推送到 dynatrace-oss/homebrew-tap。

使用方式

发布步骤（命令）：

# 1. 触发工作流，根据自上次发布以来的提交构建/更新 release PR
gh workflow run release.yml
gh run watch    # 等待 release-please 运行结束

# 2. 审查建议的版本号和说明，然后合并 release PR
gh pr list --search "chore(main): release in:title" --state open
gh pr merge <number> --squash

# 3. 再次触发，创建 tag + GitHub Release 并发布产物
gh workflow run release.yml
gh run watch

# 4. 确认
gh release view "$(gh release list --limit 1 --json tagName -q '.[0].tagName')"

版本号由提交类型决定（pre-1.0 阶段）：

提交前缀	版本提升	示例
`feat:`	MINOR	0.30.3 → 0.31.0
`fix:` / `perf:`	PATCH	0.30.3 → 0.30.4
`feat!:` / `fix!:` 或 `BREAKING CHANGE:` footer	MINOR（pre-1.0）	0.30.3 → 0.31.0
`docs:` / `test:` / `chore:` / `ci:` / `refactor:`	单独不触发发布	—

因此控制版本的方式是写好 conventional commits（参见 CONTRIBUTING.md）。PR 采用 squash 合并，PR 标题即成为与发布相关的提交。

可选：润色发布说明。release-please 生成的说明按提交类型分组并带 PR 链接，默认已足够好。如需更丰富的文字，可在发布后编辑 GitHub Release，GoReleaser 使用 keep-existing，不会覆盖你的修改：

gh release edit vX.Y.Z --notes-file notes.md

适用场景

需要为 dtctl 执行一次正式发布（cut a release / ship it）。
需要理解版本号为何如此提升、发布说明从何而来。
需要排查发布流程中的常见问题。

限制与注意事项

仓库按设计不包含 CHANGELOG.md，GitHub Release 是权威变更日志（release-please-config.json 中 skip-changelog: true）。
合并 release PR 本身不会发布任何内容，因为工作流只在手动触发时运行，必须记得第二次触发。
故障排查：没有出现 release PR——是否触发了工作流？它不会在合并时运行；若已运行仍无 PR，可能是自上次发布以来没有可发布的提交（只有 docs/chore/test 等），或某提交不是有效的 conventional commit，可检查 gh run list --workflow=release.yml。合并了 release PR 但没有发布——这是预期行为，需第二次触发工作流。版本提升错误——由提交类型导致，可在 main 上的提交中使用 Release-As: x.y.z footer 强制指定提升。创建了 release 但没有二进制——检查 release 工作流运行中的 goreleaser 任务，release-please 任务必须输出 release_created: true 它才会运行。Homebrew 未更新——检查 HOMEBREW_TAP_APP_ID / HOMEBREW_TAP_APP_PRIVATE_KEY 密钥和 GoReleaser 步骤日志；skip_upload: auto 会有意跳过预发布 tag。
检查清单：所有预期变更已以 conventional commits 合并到 main；Dispatch #1 创建/更新 release PR；打开的 release PR 反映预期版本和说明；squash 合并 release PR；Dispatch #2 创建 tag + Release；release.yml 运行的 release-please 和 goreleaser 任务均为绿色；GitHub Release 显示二进制、校验和、签名和 SBOM；（可选）通过 gh release edit 润色发布说明。

技能介绍

用途

主要能力

使用方式

适用场景

限制与注意事项