Chroma 发布流程

概览

通过对比 HEAD 与最新 tag，确定下一版 SemVer，生成符合仓库格式的 changelog 段落，同步

ca

CLI 版本号，并通过

gh

发布 git tag 与 GitHub Release。

工作流（从 HEAD 发布）

0) 前置条件

• 确保功能/修复改动已提交。release 脚本要求工作区干净。
• Tag 格式为纯

  X.Y.Z

  （不带

  v

  ）。
• Release notes 从 notes 文件读取，文件内不包含版本标题。

1) 收集变更用于 AI 分析

运行变更收集脚本：

./.codex/skills/chroma-release/scripts/collect_changes.py

如果需要指定基准 tag：

./.codex/skills/chroma-release/scripts/collect_changes.py --since-tag 0.1.1

利用输出检查：

• 上次 tag 到 HEAD 的提交摘要
• 变更文件与 diff 统计

2) 决定下一版本（SemVer）

基于 diff 与提交上下文决定下一版本号。

判定参考：

• Breaking change：删除/重命名 public API，修改函数签名，改变默认行为，或不兼容的 CLI flag 变更。
• Feature：向后兼容的新增功能。
• Fix：仅包含向后兼容的 bug 修复。

SemVer 对应：

• MAJOR

  ：破坏性变更（若已到 1.0.0+）

• MINOR

  ：新增功能

• PATCH

  ：修复

1.0 前版本处理（当前状态）：

• 0.y.z

  下的破坏性变更按 minor 处理（

  y+1

  ）。
• 功能新增按风险决定

  y+1

  或

  z+1

  ；默认用户可见新增走 minor，低风险修复走 patch。

若破坏性判断不明确，优先检查

Sources/Chroma

与 public 声明 diff 再决策。

3) 生成 changelog notes（AI）

生成与

CHANGELOG.md

现有格式一致的 notes 文件。notes 不得包含版本标题。示例：

### Added
- ...

### Changed
- ...

### Fixed
- ...

根据上次 tag 与 HEAD 的 diff 填充段落，只保留有内容的分组。

4) 应用版本 + changelog，提交、打 tag、发布（脚本化）

用选定版本和 notes 文件执行发布脚本：

./.codex/skills/chroma-release/scripts/release.py \
  --version 0.1.1 \
  --notes-file /path/to/release-notes.md \
  --date 2026-01-04

行为：

• 更新

  Sources/Ca/CaCommand.swift

  里的版本常量
• 在

  ## [Unreleased]

  之后插入

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

  段落
• 提交信息为

  Release X.Y.Z

• 创建 git tag

  X.Y.Z

• 使用同一 notes 文件通过

  gh release create

  发布 GitHub Release

可选参数：

• --skip-commit

  /

  --skip-tag

  /

  --skip-release

• --allow-dirty

  （不建议）

5) 校验

./.codex/skills/chroma-release/scripts/release_check.py --version 0.1.1 --require-clean --require-tag

资源

scripts/

• collect_changes.py

  ：收集上次 tag 到 HEAD 的提交与 diff 摘要。

• release.py

  ：应用 changelog 与 CLI 版本，提交、打 tag、发布。

• release_check.py

  ：强校验版本一致性与 tag 是否存在。