dtctl-release

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

dtctl Release Process

dtctl 发布流程

This skill walks through shipping a new dtctl release end-to-end. The process has six phases: analyze, version, changelog, test, commit/tag/push, and GitHub release notes.

此技能会逐步引导完成dtctl新版本的完整发布流程。该流程分为六个阶段：分析、版本确定、变更日志、测试、提交/打标签/推送，以及GitHub发布说明。

Prerequisites

前置条件

You must be on the
```
main
```
branch with all feature branches merged
The working tree must be clean (
```
git status
```
shows no uncommitted changes)
If the user is on a feature branch, merge to main first (or ask them to)

Pre-flight check:

bash

git branch --show-current   # Must be "main"
git status                  # Must be clean
git pull origin main        # Must be up to date with remote

If any check fails, stop and resolve before continuing.

你必须处于
```
main
```
分支，且所有功能分支已合并
工作树必须干净（
```
git status
```
显示无未提交变更）
如果用户当前在功能分支上，请先合并到main分支（或要求用户完成此操作）

预飞检查：

bash

git branch --show-current   # 必须为"main"
git status                  # 必须干净
git pull origin main        # 必须与远程仓库保持同步

如果任何检查未通过，请先解决问题再继续。

Phase 1: Analyze Changes Since Last Release

阶段1：分析上次发布后的变更

Identify what changed since the last release to determine the version bump and write good release notes.

bash

undefined

确定自上次发布以来的变更内容，以此决定版本升级幅度并撰写优质发布说明。

bash

undefined

Find the latest release tag

查找最新的发布标签

git tag --sort=-version:refname | head -5

List all commits since that tag

列出该标签之后的所有提交

git log <last-tag>..HEAD --oneline

Check the current Unreleased section in CHANGELOG.md

查看CHANGELOG.md中的[Unreleased]章节


Read the commits carefully and group them into:
- **Features** (new commands, new flags, new integrations)
- **Bug fixes** (corrected behavior)
- **Documentation** (new or updated docs)
- **Security** (dependency updates, vulnerability fixes)
- **Breaking changes** (removed flags, changed defaults)

For each significant feature, explore the actual implementation files to understand what it does. Don't just rely on commit messages — read the code so you can write accurate, detailed release notes.


仔细阅读提交记录，并将其归类为：
- **功能**（新命令、新标志、新集成）
- **Bug修复**（修正的行为问题）
- **文档**（新增或更新的文档）
- **安全**（依赖更新、漏洞修复）
- **破坏性变更**（移除的标志、修改的默认值）

对于每个重要功能，请查看实际的实现文件以了解其功能。不要仅依赖提交信息——阅读代码才能撰写准确、详细的发布说明。

Phase 2: Determine Version Number

阶段2：确定版本号

dtctl follows Semantic Versioning (currently pre-1.0, so 0.MINOR.PATCH):

Change type	Bump	Example
New features, new commands	MINOR	0.23.0 -> 0.24.0
Bug fixes only, no new features	PATCH	0.24.0 -> 0.24.1
Breaking changes (pre-1.0)	MINOR	0.24.0 -> 0.25.0

dtctl 遵循Semantic Versioning规范（当前为1.0版本前阶段，版本格式为0.MINOR.PATCH）：

变更类型	升级幅度	示例
新增功能、新命令	MINOR	0.23.0 -> 0.24.0
仅Bug修复，无新增功能	PATCH	0.24.0 -> 0.24.1
破坏性变更（1.0版本前）	MINOR	0.24.0 -> 0.25.0

Phase 3: Update Version and Changelog

阶段3：更新版本号与变更日志

3a. Bump version in code

3a. 在代码中升级版本号

Edit

pkg/version/version.go

— change the

Version

variable:

var Version = "X.Y.Z"  // update this

This is the only place the version is hardcoded. GoReleaser injects it at build time via

-ldflags

, but the fallback value here should always match the latest release.

编辑

pkg/version/version.go

——修改

Version

变量：

var Version = "X.Y.Z"  // 更新此值

这是唯一硬编码版本号的位置。GoReleaser会通过

-ldflags

在构建时注入版本号，但此处的回退值应始终与最新版本保持一致。

3b. Update CHANGELOG.md

3b. 更新CHANGELOG.md

The changelog follows Keep a Changelog format. Move items from

[Unreleased]

into a new version section:

markdown

undefined

变更日志遵循Keep a Changelog格式。将

[Unreleased]

中的条目移至新的版本章节：

markdown

undefined

[Unreleased]

[X.Y.Z] - YYYY-MM-DD

Added

Feature name — description with enough detail that users understand what it does and how to use it; include CLI examples where relevant

功能名称 —— 描述需足够详细，让用户了解功能用途及使用方法；相关处需包含CLI示例

Fixed

Bug summary — what was broken and how it's fixed now

Bug摘要 —— 说明问题所在及修复方式

Changed

Change summary — what changed and why

变更摘要 —— 说明变更内容及原因

Security

Security fix — what was vulnerable and what was upgraded

安全修复 —— 说明漏洞所在及升级内容

Documentation

Doc name — what was added or updated


Also add the comparison link at the bottom of the file:

```markdown
[X.Y.Z]: https://github.com/dynatrace-oss/dtctl/compare/vPREVIOUS...vX.Y.Z

If a comparison link for the previous version is missing (check!), add that too.

文档名称 —— 说明新增或更新的内容


同时在文件底部添加对比链接：

```markdown
[X.Y.Z]: https://github.com/dynatrace-oss/dtctl/compare/vPREVIOUS...vX.Y.Z

如果之前版本的对比链接缺失（请检查！），请一并添加。

Writing style for changelog entries

变更日志条目的撰写风格

Start each entry with a bold feature/fix name in
```
**double asterisks**
```
Follow with an em dash
```
—
```
and a description
Be specific: mention command names, flag names, file paths, environment variables
For features, explain both what it does and how to use it
For fixes, explain what was broken and what the correct behavior is now
Use semicolons to chain related details in a single entry
Keep entries to 1-3 lines each

每个条目以
```
**双星号**
```
包裹的加粗功能/修复名称开头
后跟破折号
```
—
```
及描述内容
内容要具体：提及命令名称、标志名称、文件路径、环境变量
对于功能，需说明用途及使用方法
对于修复，需说明问题所在及正确行为
使用分号连接单个条目中的相关细节
每个条目保持1-3行

Phase 4: Run Tests

阶段4：运行测试

Run the full test suite and build to catch any issues before releasing:

bash

undefined

运行完整测试套件并构建，在发布前发现所有问题：

bash

undefined

Run all tests

运行所有测试

go test ./...

Build the binary

构建二进制文件

make build

Verify the build works

验证构建结果

./bin/dtctl version


All tests must pass. If any fail, fix them before proceeding.

./bin/dtctl version


所有测试必须通过。如果有测试失败，请先修复再继续。

Phase 5: Commit, Tag, and Push

阶段5：提交、打标签与推送

5a. Commit the release

5a. 提交发布变更

bash

git add CHANGELOG.md pkg/version/version.go
git commit -m "release vX.Y.Z: short summary of key features"

The commit message should follow the pattern:

release vX.Y.Z: feature1, feature2, feature3

bash

git add CHANGELOG.md pkg/version/version.go
git commit -m "release vX.Y.Z: 关键功能简短摘要"

提交信息需遵循以下格式：

release vX.Y.Z: feature1, feature2, feature3

5b. Push and tag

5b. 推送并打标签

bash

git push origin main
git tag vX.Y.Z
git push origin vX.Y.Z

Pushing the tag triggers the GitHub Actions release workflow (

.github/workflows/release.yml

), which automatically:

Builds cross-platform binaries (linux/darwin/windows, amd64/arm64)
Signs checksums with cosign (keyless, via OIDC)
Generates SBOMs with syft
Creates a GitHub Release with auto-generated changelog
Pushes an updated Homebrew cask to
```
dynatrace-oss/homebrew-tap
```

bash

git push origin main
git tag vX.Y.Z
git push origin vX.Y.Z

推送标签会触发GitHub Actions发布工作流（

.github/workflows/release.yml

），该工作流将自动：

构建跨平台二进制文件（linux/darwin/windows，amd64/arm64）
使用cosign（无密钥，通过OIDC）对校验和签名
使用syft生成SBOM
创建包含自动生成变更日志的GitHub Release
将更新后的Homebrew cask推送到
```
dynatrace-oss/homebrew-tap
```

Homebrew

No manual Homebrew update is needed. GoReleaser's

homebrew_casks

config in

.goreleaser.yaml

automatically pushes the updated cask to the tap repository using a GitHub App token. The

skip_upload: auto

setting prevents pre-release tags from being published.

无需手动更新Homebrew。

.goreleaser.yaml

中的GoReleaser

homebrew_casks

配置会使用GitHub App令牌自动将更新后的cask推送到tap仓库。

skip_upload: auto

设置可防止预发布标签被发布。

Phase 6: Write GitHub Release Notes

阶段6：编写GitHub发布说明

After the tag is pushed, update the GitHub release with polished release notes. The auto-generated changelog from GoReleaser is a raw commit list — replace it with proper release notes.

bash

gh release edit vX.Y.Z --notes "$(cat <<'EOF'
... release notes here ...
EOF
)"

推送标签后，使用优化后的发布说明更新GitHub Release。GoReleaser自动生成的变更日志是原始提交列表——需将其替换为规范的发布说明。

bash

gh release edit vX.Y.Z --notes "$(cat <<'EOF'
... 发布说明内容 ...
EOF
)"

Release notes format

发布说明格式

Follow this exact structure (see previous releases for reference —

gh release view vPREVIOUS

markdown

undefined

请严格遵循以下结构（可参考过往版本——

gh release view vPREVIOUS

）：

markdown

undefined

What's New

新功能

Feature Name

功能名称

Paragraph explaining the feature with context on why it's useful.

```bash

段落说明功能用途及实用场景。

```bash

Concrete usage example

具体使用示例

dtctl some-command --some-flag ```

Additional detail about configuration, behavior, or edge cases. Keep it practical — show users exactly how to use the feature.

dtctl some-command --some-flag ```

关于配置、行为或边缘情况的额外细节。内容需实用——向用户展示功能的具体使用方法。

Another Feature

另一项功能

...repeat for each major feature...

...为每个主要功能重复上述结构...

Bug Fixes

Bug修复

Short fix title — one-line explanation of what was broken and what's fixed.
Another fix — description.

简短修复标题 —— 一行说明问题所在及修复内容。
另一项修复 —— 说明内容。

Documentation

文档

Doc title — what was added, with a link if applicable.

文档标题 —— 说明新增或更新的内容，如有需要可附带链接。

Install / Upgrade

安装/升级

```bash

Homebrew

brew update && brew upgrade dtctl

Direct install

直接安装

curl -fsSL https://raw.githubusercontent.com/dynatrace-oss/dtctl/main/install.sh | bash

Go install

Go安装

go install github.com/dynatrace-oss/dtctl@vX.Y.Z ```

Full Changelog: https://github.com/dynatrace-oss/dtctl/compare/vPREVIOUS...vX.Y.Z

undefined

go install github.com/dynatrace-oss/dtctl@vX.Y.Z ```

完整变更日志: https://github.com/dynatrace-oss/dtctl/compare/vPREVIOUS...vX.Y.Z

undefined

Release notes writing style

发布说明撰写风格

Each major feature gets its own
```
### Heading
```
with a paragraph + code example
Code examples should be copy-pasteable and realistic
Bug fixes go in a single bulleted list under
```
## Bug Fixes
```
Always end with the
```
## Install / Upgrade
```
block
Always end with the
```
**Full Changelog**
```
comparison link
Omit sections that don't apply (e.g., no
```
## Security
```
if there are no security fixes)
Study previous releases for tone and detail level:
```
gh release view v0.23.0
```
,
```
gh release view v0.22.0
```

每个主要功能单独使用
```
### 标题
```
，并附带段落+代码示例
代码示例应可直接复制使用且符合实际场景
Bug修复需放在
```
## Bug修复
```
下的单个项目符号列表中
结尾必须包含
```
## 安装/升级
```
模块
结尾必须包含
```
**完整变更日志**
```
对比链接
可省略不适用的章节（例如：无安全修复时可省略
```
## 安全
```
章节）
可参考过往版本的语气和详细程度：
```
gh release view v0.23.0
```
,
```
gh release view v0.22.0
```

Checklist

检查清单

Use this to track progress:

On
```
main
```
branch, clean working tree, up to date with remote
Analyzed all commits since last release
Determined version number (semver)
Updated
```
pkg/version/version.go
```
Updated
```
CHANGELOG.md
```
(entries + comparison link)
Tests pass (
```
go test ./...
```
)
Build succeeds (
```
make build
```
)
Committed release changes on
```
main
```
Pushed to
```
origin/main
```
Created and pushed tag
```
vX.Y.Z
```
GitHub release notes written via
```
gh release edit
```

使用此清单跟踪进度：

处于
```
main
```
分支，工作树干净，与远程仓库同步
分析了上次发布后的所有提交
确定了版本号（遵循语义化版本规范）
更新了
```
pkg/version/version.go
```
更新了
```
CHANGELOG.md
```
（条目+对比链接）
测试通过（
```
go test ./...
```
）
构建成功（
```
make build
```
）
在
```
main
```
分支提交了发布变更
推送到
```
origin/main
```
创建并推送了标签
```
vX.Y.Z
```
通过
```
gh release edit
```
编写了GitHub发布说明