release-changelog-harness

发布与变更日志规范

让发布内容一目了然：每次版本升级都有结构化意图，供 Agent 和人类在 Git 中查阅，而不仅仅存在于维护者的脑海中或 GitHub Releases 的文本框里。

这项技能关注的是元规范文化（使用什么工具、设置哪些门禁、文档放在哪里），不是每种包管理器的完整教程。

专家视角汇总——审视你的想法

专家视角	对“到处都用 JS Changesets”的评价
JS 单体仓库维护者	很适合作为默认方案：.changeset/*.md + changeset version，胜过手动编辑五个 package.json 文件。
Dart / Flutter 发布者	直接套用并不合适：pub 使用标签 + CHANGELOG.md；单体仓库通常使用 Melos 的 version / changelog，而非 npm Changesets。
Rust / Go 发布者	使用 release-plz、cargo-release 或 git-cliff——强推 Changesets 会引入格格不入的工作流。
Agent 运维者	当变更说明以小型结构化文件的形式保存在 Git 中，供 Agent 阅读并用于 PR 时，效果最佳——而不是只存在于 Slack 的纯文本中。
多仓库负责人（~/mcp）	所有关联仓库遵循同一份清晰度契约；不同生态使用不同生成器完全没问题。
技能维护者准则	说明何时使用、门禁要求和文档位置；链接到上游文档；不要把 200 行配置粘贴进 SKILL.md。

优化后的表述（请采用）：

先采用发布清晰度契约；再选择符合生态习惯的生成器（Changesets 是 JS 工作区的优秀生成器之一，但不是放之四海而皆准的工具）。

延伸讨论和反模式请参见 mixture-of-experts.md。

发布清晰度契约（规范性要求）

选择工具之前，先确保仓库遵循以下要求：

1. 变更说明保存在 Git 中——变更日志或 changeset 文件都应纳入版本控制；不能只把发布说明放在网页 UI 中。
2. 贡献者输入有固定结构——贡献者以固定格式补充意图（例如 .changeset/foo.md、conventional commit 的 scope 或 ADR 说明），而不是“记得时再升级版本”。
3. 发布流程可机械执行——在 DX_FAQ 中记录一组明确的命令；对于“能否发布”，CI 是事实依据。
4. 输出可供 Agent 阅读——发布完成后，CHANGELOG.md（或各个包的变更日志）应反映已发布内容；Agent 能回答“vX 有哪些变化？”
5. 记录选择原因——工具链选择如非显而易见，应记录简短的 ADR 或 DESIGN_FAQ 问答。
6. 安装信息与发布事实一致——最新的 GitHub Release、发布资源、校验和、包版本和安装文档必须一致；过时的固定版本安装示例会造成发布信息偏差。

生态系统路由（默认模式）

仓库信号	默认工具	备注
pnpm-workspace.yaml / npm workspaces	@changesets/cli	JS 单仓库的行业标准；搭配 GitHub Action 使用。
单个 Node 软件包，发布频率高	release-please 或 Changesets	release-please = 常规提交 → PR；Changesets = 明确的人工/Agent 意图文件。
Dart 单仓库（melos.yaml）	Melos version + 更新日志	与 DX_FAQ 中的 pub 发布顺序保持一致。
单个 Dart 软件包	CHANGELOG.md + git tag + dart pub publish	条目应采用 Agent 可编辑的 Markdown 格式。
Rust 工作区	release-plz 或 cargo-release + git-cliff	优先选择可自动创建版本 PR 的工具。
带二进制文件的产品工具框架	release-please + tag CI + install.sh	不要添加第二个版本来源；遵循 binary-release-contract.md
元项目 + CLI 二进制文件（Skill Steward）	Changesets + 单个 Release 工作流 + install.sh	版本 PR 首先更新 git 中的真实记录；Release 工作流负责打 tag、构建资源、创建/更新 GitHub Release，并根据 ADR 0014 验证 latest/install 的可信度

完整矩阵：ecosystem-tooling.md。二进制文件/安装：binary-release-contract.md。

何时使用此技能

• “我们应该像 JS 社区一样使用 Changesets”
• 发布流程不明确、版本不一致，或 Agent 无法判断已发布的内容
• 添加发布 CI、版本策略或单仓库发布工作流
• 审核更新日志工具是否与仓库类型相符（repo-quality-system-lifecycle）

工作流

1. 对仓库分类

使用 repo-quality-system-lifecycle 的类型（应用、库、CLI/工具、插件、工具框架、元项目/治理）。元项目和工具框架仓库需要清晰易懂；应用仓库既要清晰易懂，也需要运行时兼容性说明。

2. 选择生成器（非显而易见时记录 ADR）

问题	如果是 →
有多个可发布的 JS 软件包？	Changesets（默认）
单个软件包，由提交消息驱动发布？	release-please
维护者会为每个 PR 编写明确的发布说明？	Changesets
主要使用 Pub 或 Cargo？	使用上方的生态系统表格，而非 Changesets

如果有多个合理选项，请在 docs/decisions/NNNN-release-changelog-tooling.md 中记录选择。

3. 接入工具框架各环节

环节	操作
DX_FAQ	记忆宫殿区块：添加 changeset、版本、发布、验证 tag
CI	如果 changesets/更新日志策略不合规，则阻止发布/tag；对于二进制文件，使用单一发布负责人，或明确的 workflow_run/PAT 交接
AGENTS.md	在文档路由表中添加一行，无需撰写完整的 Changesets 说明
CONTRIBUTING	“每个面向用户的 PR 都要添加 changeset 或 CHANGELOG 条目”

4. 最简 Changesets 结构（JS 单仓库和私有软件包）

贡献者添加：

---
"package-name": patch
---

Short imperative summary agents can quote in release notes.

私有软件包和公开 Tags

默认情况下，Changesets 会忽略 package.json 中标记为 "private": true 的软件包。若要允许私有根软件包或私有工作区模块升级版本，请更新 .changeset/config.json，加入：

  "privatePackages": {
    "version": true,
    "tag": false
  }

当自定义发布脚本负责创建公开的 vX.Y.Z tag 时，使用 "tag": false。仅当 Changesets 本身应创建软件包专属 tag 时，才使用 "tag": true。

维护者流程：

pnpm changeset          # or npx @changesets/cli
pnpm changeset version
pnpm install            # if lockfile must update
git commit -am "chore: version packages"

发布：由项目决定（changeset publish、GitHub Action 或 npm provenance）——请在 DX_FAQ 中记录确切命令，不要写在这里。

对于自动化的 Changesets 发布，建议使用：

merge feature PR with changeset
→ CI opens/updates Version PR
→ merge Version PR
→ same Release workflow creates vX.Y.Z, builds artifacts, creates/updates GitHub Release, verifies latest release state

如果使用 GITHUB_TOKEN 推送 tag，不要依赖单独的 on: push: tags 工作流来构建资源；GitHub 会抑制由该令牌触发的递归工作流。

5. 选择分发方式

交付单元	模式
可执行 MCP/CLI	GitHub Release 二进制文件 + 校验和 + install.sh — binary-release-contract.md
仅技能	npx skills add owner/repo — 不向使用者提供仓库 tarball
库	按生态系统表使用 pub.dev / npm / crates.io

**Skill Steward：**通过 npx skills 分发技能；通过 GitHub Releases 和 install.sh 分发预编译的 AOT 二进制文件 steward_cli（ADR 0014）。

6. 验证可读性

• Agent 无需 GitHub API 即可从 git 中读取“尚未发布的内容”
• 版本升级缺少说明时，CI 会失败
• DX_FAQ 列出的命令可直接复制粘贴
• 不存在重复的版本来源（例如手动升级 + 机器人升级）
• 如果有二进制文件：标签资源与版本 SSOT 一致；最新 GitHub Release 指向包版本；install.sh 默认使用最新版本，固定版本示例使用占位符或生成的校验值

反模式

反模式	不利之处
仅包含 Rust 的仓库使用 Changesets	与团队习惯不符；贡献者会忽略它
仅在 GitHub Releases 上提供变更日志	处于仓库上下文中的 Agent 看不到它
在 AGENTS.md 中放置 1,000 行的发布文档	挤占任务上下文；这类内容应放在 DX_FAQ / ADR 中
跳过 Changesets，“因为 AI 会在发布时编写 CHANGELOG”	不确定；无法在 PR 阶段审查
版本升级时没有面向使用者的说明	用户和 Agent 无法评估升级风险
发布二进制文件，但 git 中没有变更日志	用户能看到版本；Agent 看不到发布意图
GITHUB_TOKEN 推送标签后，单独运行由标签触发的二进制工作流	GitHub 会抑制递归工作流触发；最新发布和资源可能悄然滞后
安装示例中固定使用真实的旧版本	README/DX 与 GitHub Releases/install.sh 内容不一致
将 git clone 作为服务产品的终端用户安装方式	使用 install.sh + Release 资源（二进制发布模式）

相关技能

技能	适用场景
repo-quality-system-lifecycle	仓库类型、机械化门禁、证据路径
mcp-harness-repo-maintainer	类型化操作、探测、基准测试、CLI/MCP 一致性
repository-governance-lifecycle	ADR、DESIGN_FAQ/DX_FAQ 更新及计划规范
skill-source-citations	持久化的发布工具来源

安装

npx skills add arenukvern/skill_steward --skill release-changelog-harness

来源

references/sources.md