changelog-capture

Readme

# changelog-capture 变更日志捕获

The changelog nobody writes costs everyone: the teammate who misses a breaking change, the user who cannot tell whether to upgrade, and you, six weeks later, reconstructing what a release changed.

没人写的 changelog 让所有人买单：错过 breaking change 的同事、不知道该不该升级的用户、六周后重建"这版到底改了啥"的你自己。

## Why / 为什么

Commit messages serve the code; changelogs serve the **people the code changed things for**. The failure mode is writing the log from memory at release time — memory that has already blurred which changes mattered. Capture at change time: one entry while the diff is still in hand costs a minute; the release note assembles itself.

commit message 服务代码；changelog 服务**被代码改变了生活的人**。失败模式是发版时凭记忆补写——而记忆早就分不清哪些改动要紧。在改动当下捕获：diff 还在手边时写一条只要一分钟，发版说明自己就组装好了。

## The entry shape / 条目形状

```
### Changed — CSV import now maps date columns automatically (was: manual mapping)
Who: everyone importing CSV exports from other tools
Upgrade: re-run the import preview once; check the mapped dates before confirming
```

- **Who** — which users the change touches (or "everyone")
- **What** — one sentence, behavior stated
- **How to upgrade** — the action required, or "nothing"

## The rules that keep it honest / 保持诚实的规则

- **Separate Added / Changed / Fixed / Breaking** — a "fix" that changes behavior is a Changed, and a Breaking section sits at the top, never buried.
- **Verify against the diff.** At release time, each entry is checked against the actual changes: the log claims what the diff does, and anything in the diff that touches users gets an entry.
- **No log for no behavior change.** Internal refactors get a line only if someone outside the code can tell the difference.

## Honest limitations / 如实说明局限

- "User-facing" is a judgment call; internal API changes that leak into SDKs will occasionally surface without an entry until reported.
- The diff-reconciliation is only as complete as the diff — squashed or amended histories need the real change list.

"用户可见"是个判断题；内部 API 变更漏进 SDK 时，偶尔会在被报告前没有条目。diff 对账只与 diff 一样完整——被 squash 的历史需要真正的变更清单。

## Install / 安装

```bash
npx skills add ChenneyZhuang/changelog-capture
```

Per-agent paths: [COMPATIBILITY.md](COMPATIBILITY.md). MIT. v0.1.0.

各 agent 安装路径见 COMPATIBILITY.md。MIT 许可，v0.1.0。