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 是否存在。