[0.17.0] - 2026-02-15

[0.17.0] - 2026-02-15

Added

• rtk pytest command for Python test filtering (90% token reduction)
• Support for pytest JSON output parsing
• Integration with uv package manager auto-detection

Fixed

• Shell escaping for PowerShell on Windows
• Memory leak in regex pattern caching

Changed

• Updated cargo test filter to show test names in failures

从源码结构看，版本号之所以只需改 `Cargo.toml` 一处，是因为 [src/main.rs#L67](https://gitcode.com/GitHub_Trending/rtk4/rtk/blob/e8541d1e1180f7ef4c736322cedc8e834f2f8f77/src/main.rs?utm_source=gitcode_repo_files#L67) 在 clap `Command` 构造中声明了 `version` 属性——clap 会自动从 Cargo 元数据读取版本并在 `rtk --version` 时打印。仓库内也有对应测试固化这一行为：[src/main.rs#L3097-L3101](https://gitcode.com/GitHub_Trending/rtk4/rtk/blob/e8541d1e1180f7ef4c736322cedc8e834f2f8f77/src/main.rs?utm_source=gitcode_repo_files#L3097-L3101) 断言 `Cli::try_parse_from(["rtk", "--version"])` 必须触发 `DisplayVersion`。

## Step 3：构建并验证

文档的构建验证步骤：

```bash
# Clean build
cargo clean
cargo build --release

# Verify binary
target/release/rtk --version
# Should show new version

# Run full quality checks
cargo fmt --all --check
cargo clippy --all-targets
cargo test --all

# Benchmark performance
hyperfine 'target/release/rtk git status' --warmup 3
# Should still be <10ms

流程要点：cargo clean 强制全量重编译，排除增量构建缓存导致的"版本没生效"假象；rtk --version 是版本 bump 的直接验收标准（对应上一条的 clap 机制）；质量检查与性能基准在"干净构建产物"上复跑一遍，确保验证对象与将被发布的产物完全一致。

Step 4–6：提交、打 Tag、推送

提交版本 bump

# Stage version files
git add Cargo.toml Cargo.lock README.md

# Commit with version tag
git commit -m "chore(release): bump version to v0.17.0

- Updated Cargo.toml version
- Verified all quality checks pass
- Benchmarked performance (<10ms startup)

Co-Authored-By: Claude Sonnet 4.5 <[e-mail]>"

Co-Authored-By 行体现了该技能的使用场景——由 Claude Code 代理执行发布流程时的署名约定。提交类型沿用 conventional commits 的 chore(release):，这类提交不会进入 release-please 的功能/修复统计，避免对下一个版本号产生干扰。

创建带 changelog 摘录的注释 tag

# Create annotated tag with changelog excerpt
git tag -a v0.17.0 -m "Release v0.17.0

Added:
- rtk pytest command (90% token reduction)
- Support for uv package manager

Fixed:
- Shell escaping for PowerShell
- Memory leak in regex caching

Performance: <10ms startup, <5MB memory"

使用 annotated tag（git tag -a）而非 lightweight tag：tag 消息本身携带本版变更摘要与性能指标，成为 release notes 的内容来源。

推送触发 CI/CD

# Push commit and tags
git push origin main
git push origin v0.17.0

# Trigger GitHub Actions release workflow
# (CI/CD will build binaries, create GitHub release, publish to crates.io if configured)

一个需要结合仓库现状修正的细节：从 cd.yml#L5-L6 的触发条件 branches: [develop, master] 以及 CONTRIBUTING.md#L231-L236 描述的分支流（your branch → develop → version branch → master）可以推断，当前仓库的主干分支名是 master（开发分支为 develop），文档示例中的 origin main 在实际执行时应替换为仓库真实分支名。

tag 推送之后：CI/CD 实际做了什么

文档只说"触发 GitHub Actions release workflow"，具体管线在 release.yml 中完整可见。该工作流通过 workflow_call（输入 tag 与可选 prerelease）被调用，包含四类 job：

1. 多平台二进制构建（build job）——矩阵覆盖 5 个目标（release.yml#L37-L58）：

Target	平台	产物格式	构建方式
x86_64-apple-darwin	macOS	tar.gz	原生
aarch64-apple-darwin	macOS	tar.gz	原生（Apple Silicon runner）
x86_64-unknown-linux-musl	Linux	tar.gz	musl 静态链接（安装 musl-tools）
aarch64-unknown-linux-gnu	Linux	tar.gz	交叉编译（aarch64-linux-gnu 链接器）
x86_64-pc-windows-msvc	Windows	zip	原生

2. 包管理器格式——build-deb job 用 cargo-deb 生成 DEB 包，build-rpm job 在 Fedora 容器内用 cargo-generate-rpm 生成 RPM（release.yml#L108-L161）。

3. Release 创建（release job）——汇总全部产物后：生成 checksums.txt（sha256sum *，release.yml#L210-L213）、为 deb/rpm 创建不含版本号的别名文件名（rtk_amd64.deb、rtk.x86_64.rpm，便于升级脚本固定引用），最后经 softprops/action-gh-release 上传到 tag 对应的 GitHub Release（release.yml#L215-L221）。

4. 下游分发——非预发布版本还会触发 Discord 通知与 Homebrew formula 更新：homebrew job 下载 checksums.txt、解析四个平台的 sha256，用 sed 填充 Formula/rtk.rb 同构的模板后推送至 tap 仓库（release.yml#L260-L370）。

此外 cd.yml 承接 develop 分支的"预发布流"：按前文所述的 release-please 同款规则计算下一版本，打上 dev-X.Y.Z-rc.N tag 并走 prerelease 构建，让未合入主干的特性也能提前拿到可安装二进制。

发布后验证（Post-Release Verification）

文档给出的三步验证命令：

1. CI/CD 通过

gh run list --limit 1   # Check workflow status
gh run watch            # Watch latest run

2. Release 已创建

gh release view v0.17.0
# Should show:
# - Release notes from git tag
# - Binaries attached (macOS, Linux x86_64/ARM64, Windows)
# - Checksums for verification

3. 安装验证

curl -sSL https://github.com/rtk-ai/rtk/releases/download/v0.17.0/rtk-macos-latest -o rtk
chmod +x rtk
./rtk --version
# Should show v0.17.0

对照 release.yml 与 install.sh#L92-L97，实际的 release 资产命名为 rtk-<target-triple>.tar.gz（如 rtk-aarch64-apple-darwin.tar.gz、rtk-x86_64-unknown-linux-musl.tar.gz），外加 checksums.txt 与 deb/rpm 包——文档示例中的 rtk-macos-latest 只是示意，实际下载时应以 release 页的资产列表为准。官方安装脚本 install.sh 的取版本方式也值得注意：它优先解析 GET /releases/latest 的 302 重定向拿到 tag（不消耗 API 配额），失败才回退到 REST API（install.sh#L51-L67），这正是"发布资产命名必须稳定可推断"对发布流程的硬约束。

回滚预案：三层递进

文档为发布事故设计了三种回滚手段，按侵入性从低到高排列：

Option 1：Patch 热修复（首选）

# Fix issue in new branch
git checkout -b hotfix/v0.17.1
# Apply fix
cargo test --all
git commit -m "fix: critical issue in pytest filter"

# Release v0.17.1 (PATCH bump)
# Follow release workflow above

保留已发布 tag 与 release 不动，仅追加一个 PATCH 版本，用户按 latest 安装时自然获取修复版。

Option 2：Yank 版本（仅 crates.io 生效）

# Yank broken version from crates.io
cargo yank --vers 0.17.0

# Users can't download yanked version, but existing installs work

适用边界需要说明：yank 只对已发布到 crates.io 的版本生效。从当前仓库快照的 workflow 看，发布产物走 GitHub Release + Homebrew tap，未见 cargo publish 步骤（与文档 "publish to crates.io if configured" 的措辞一致）——若未发布到 crates.io，此选项不适用，应直接选 Option 1 或 3。

Option 3：删除 tag（最后手段）

# Delete tag locally
git tag -d v0.17.0

# Delete tag on remote
git push origin :refs/tags/v0.17.0

# Delete GitHub release
gh release delete v0.17.0 --yes

# Revert commit
git revert HEAD
git push origin main

删除 tag 与 release 会同时切断下游分发链（Homebrew formula 中引用的下载 URL 将失效），因此文档将其定为 last resort，并且 tag 删除后要 git revert HEAD 回退版本 bump 提交，让主干恢复到发布前状态。

可选自动化：scripts/ship.sh

文档末尾附了一段可将全流程压缩为一条命令的 bash 脚本（保存为 scripts/ship.sh 后以 ./scripts/ship.sh 0.17.0 调用）。当前仓库的 scripts/ 目录中并无此文件，它是文档给出的可选自动化方案，需要使用者自行落盘。脚本全文：

#!/bin/bash
set -euo pipefail

# Parse version argument
if [ $# -ne 1 ]; then
    echo "Usage: $0 <version>"
    echo "Example: $0 0.17.0"
    exit 1
fi

NEW_VERSION=$1

echo "🚀 Starting release workflow for v$NEW_VERSION"

# 1. Quality checks
echo "📦 Running quality checks..."
cargo fmt --all --check
cargo clippy --all-targets
cargo test --all

# 2. Update version
echo "🔢 Updating version to $NEW_VERSION..."
sed -i '' "s/^version = .*/version = \"$NEW_VERSION\"/" Cargo.toml

# 3. Build
echo "🔨 Building release binary..."
cargo build --release

# 4. Verify version
echo "✅ Verifying version..."
target/release/rtk --version | grep "$NEW_VERSION"

# 5. Commit
echo "💾 Committing version bump..."
git add Cargo.toml Cargo.lock
git commit -m "chore(release): bump version to v$NEW_VERSION

Co-Authored-By: Claude Sonnet 4.5 <[e-mail]>"

# 6. Tag
echo "🏷️  Creating git tag..."
git tag -a "v$NEW_VERSION" -m "Release v$NEW_VERSION"

# 7. Push
echo "🚢 Pushing to remote..."
git push origin main
git push origin "v$NEW_VERSION"

echo "✅ Release v$NEW_VERSION shipped!"
echo "Monitor CI/CD: gh run watch"

使用方式：

chmod +x scripts/ship.sh
./scripts/ship.sh 0.17.0

移植时有三个实操要点：

• set -euo pipefail 保证任一步骤失败即中止，避免"版本改了但测试没跑过"的半成品发布；
• sed -i '' 是 BSD sed（macOS） 的空备份文件语法，在 Linux（GNU sed）上需改为 sed -i，跨平台使用时建议按 uname 分支处理；
• 脚本省略了文档 Step 3 中的性能基准与 CHANGELOG 相关操作——这与"CHANGELOG 由 release-please 自动生成"的约定一致，但意味着若依赖人工卡性能线，需在脚本中自行补回 hyperfine 步骤。

发布节奏与版本历史参考

推荐发布节奏

版本类型	节奏建议
PATCH	关键 bug 随时发（24h 内响应）
MINOR	每周或双周（随新功能合入）
MAJOR	每季度，或出现破坏性变更时

查看版本历史

git tag -l "v*"        # List all version tags
git log --oneline --tags  # Show commits with tags

文档给出的示例输出：

v0.17.0 (HEAD -> main, tag: v0.17.0, origin/main)
v0.16.0
v0.15.1
v0.15.0

当前仓库的版本历史可以直接用 git tag -l 'v*' 复核，与 .release-please-manifest.json、Cargo.toml 及 CHANGELOG.md 三者保持同一版本事实源——这也是整套流程"单一版本源"设计在历史维度上的体现。

常见问题排查（Common Issues）

问题一：tag 推送后 CI/CD 失败

症状：GitHub Actions 在 release 构建阶段失败。 解法（本地修复 + 重建 tag）：

# Fix issue locally
git checkout main
# Apply fix
cargo test --all
git commit -m "fix: CI/CD build issue"
git push origin main

# Delete old tag
git tag -d v0.17.0
git push origin :refs/tags/v0.17.0

# Create new tag
git tag -a v0.17.0 -m "Release v0.17.0 (rebuild)"
git push origin v0.17.0

思路是"修复先行、tag 后补"：先让主干包含修复，再删旧 tag 重建同版本 tag 重新触发 release.yml。

问题二：版本不生效（Version Mismatch）

症状：bump 之后 rtk --version 仍显示旧版本。 解法：

# Cargo.lock might be out of sync
cargo update -p rtk
cargo build --release

# Verify
target/release/rtk --version

根因是 Cargo.lock 中记录的自身包版本与 Cargo.toml 不一致（lock 文件缓存了旧版本），cargo update -p rtk 强制同步本包条目。这也解释了文档 Step 4 为何要把 Cargo.lock 与 Cargo.toml 一并 git add。

问题三：CHANGELOG.md 合并冲突

症状：rebase 后 CHANGELOG.md 出现冲突。 解法：不要手工编辑 CHANGELOG.md——它由 release-please 在合并时根据 conventional commits 自动生成（与 CONTRIBUTING.md 的约定一致）。冲突时应让 release-please 的发布 PR 重新生成，而非人工调和两侧文本。

安全考虑（Security Considerations）

文档要求发布前完成一份安全检查清单：

• [ ] 代码中无密钥（API keys、tokens）
• [ ] 无 .env 文件被提交
• [ ] 依赖已扫描（cargo audit）
• [ ] Shell 注入漏洞已复查
• [ ] 跨平台 shell 转义已测试

依赖审计的标准流程：

cargo install cargo-audit
cargo audit

# Example output:
# Crate: some-crate
# Version: 0.1.0
# Warning: vulnerability found
# Advisory: CVE-2024-XXXXX

若发现漏洞：

# Update vulnerable dependency
cargo update some-crate

# Verify fix
cargo audit

# Re-run quality checks
cargo test --all