Release

发布工作流

此技能提供了一个系统化工作流，用于创建和发布 linear-cli 项目的版本。它负责管理变更日志、提升版本号、运行测试和打标签。

使用时机

准备发布 linear-cli 新版本时使用此技能。此工作流可确保所有变更均有记录、测试通过，并且版本在发布前已正确打标签。

前置条件

确保以下工具可用：

• 用于管理变更日志的 changelog 技能
• 用于提升版本号的 svbump（已安装）
• 用于版本控制操作的 jj
• 用于运行发布任务的 just
• 用于更新 Claude Code 插件版本的 jq

发布工作流

步骤 1：查看上次发布以来的提交

确定自上次发布以来的提交：

jj log --ignore-working-copy --git -r 'tags()..@' --no-graph

这会显示从最近的标签到当前提交的所有提交。

步骤 2：添加变更日志条目

对于上面列出的每个提交，判断是否需要添加变更日志条目。重点关注面向用户的变更：

纳入变更日志：

• 新功能
• Bug 修复
• 破坏性变更
• 重要改进
• 弃用事项

不纳入变更日志：

• 不影响用户的内部重构
• 仅涉及文档的变更
• 构建/CI 配置变更
• 杂项提交（除非影响重大）

使用 changelog CLI 添加条目。使用提交 SHA 作为 --attribute-pr 的值，自动查找关联的 PR 并添加署名；schpet 和 schpetbot 除外：

changelog add --type <type> "<description>" --attribute-pr <commit-sha> --exclude-users schpet,schpetbot

对于没有关联 PR 的提交，或不需要署名时，请省略 --attribute-pr。

类型对应 Keep a Changelog 的类别：

• added - 新功能
• changed - 现有功能的变更
• deprecated - 即将移除的功能
• removed - 已移除的功能
• fixed - Bug 修复
• security - 安全性改进

步骤 3：与用户核对变更日志

添加所有相关的变更日志条目后，向用户展示 CHANGELOG.md 中尚未发布的部分，并请其审核：

1. 读取 CHANGELOG.md 文件
2. 展示 [Unreleased] 部分
3. 询问：“请审核这些变更日志条目。发布前是否需要进行任何更改？”
4. 按要求进行调整

步骤 4：确定 Semver 版本提升级别

根据变更日志中的变更类型，确定并建议适当的语义化版本提升级别：

Major（X.0.0）：

• 破坏性变更
• 已移除的功能
• 重要 API 变更

Minor（0.X.0）：

• 新功能（added）
• 弃用事项
• 向后兼容的功能新增

Patch（0.0.X）：

• Bug 修复
• 安全修复
• 不包含新功能的小幅改进

向用户说明建议：

Based on the changelog entries, I recommend a <MAJOR/MINOR/PATCH> version bump because:
- [reason 1]
- [reason 2]

Current version: <current>
Proposed version: <proposed>

Should I proceed with this version bump?

等待用户确认后再继续。

步骤 5：运行变更日志发布命令

用户确认版本提升级别后，使用相应的 semver 级别运行变更日志发布命令：

changelog release <major|minor|patch>

此命令会更新 CHANGELOG.md，将 Unreleased 部分转换为带版本号的发布记录。

第 6 步：执行 Tag 流程

变更日志发布后，运行 tag 配方：

just tag

它会按顺序执行整个发布流程，并在首次失败时停止：

1. 质量检查（just check）：cargo fmt --all --check、cargo clippy --locked --workspace --all-targets -- -D warnings 和 cargo test --locked --workspace
2. 版本更新： 使用 svbump 将最新的变更日志版本写入 Cargo.toml 中的 workspace.package.version，然后使用 cargo update --workspace 更新 Cargo.lock
3. Skill 文档（just skill-docs）：根据 CLI 帮助信息重新生成 skills/linear-cli/SKILL.md 及其参考文档
4. 插件版本（just plugin-version）：设置 .claude-plugin/plugin.json 中的 version，以及 .claude-plugin/marketplace.json 中的 version 和 plugins[0].version
5. 提交并打标签： 执行 jj commit -m "chore: Release linear-cli version <version>"，然后将 main 书签移动到该提交，并在该提交（@-）上设置 v<version> 标签
6. 推送： 执行 jj git push --bookmark main，然后执行 git push origin --tags

完成后会打印 released v<version>。

错误处理

如果任一步骤失败：

• 质量检查失败： 先修复问题，再继续。如果测试失败或存在 lint 错误，请勿继续发布。
• 版本更新失败： 确认版本格式正确且文件存在。
• 推送失败： 检查身份验证和远程访问权限。

始终停止并清楚地报告错误。如果关键步骤失败，切勿继续发布流程。

重要说明

• justfile 中的 tag 配方会运行上述所有步骤；无需手动逐一执行
• 按照项目的 AGENTS.md 要求，所有版本控制操作都使用 jj
• 对只读的 jj 操作始终使用 --ignore-working-copy
• 此工作流会在父提交（@-）上创建一个提交，然后创建一个新的工作提交
• jj git push 和 git push origin --tags 都不可少（jj 用于推送书签，git 用于推送标签）

发布后

发布成功后：

1. 确认 GitHub 上显示了该标签
2. 检查 GitHub Actions 发布工作流（.github/workflows/release.yml）是否构建了二进制文件并发布 Homebrew formula 和 npm 包
3. 确认新版本已发布

参考

实现详情请参阅 justfile 中的 tag 和 plugin-version 配方。