Changelog from commits

Changelog from Commits / 提交转更新日志

When to use

• The user is cutting a release and needs user-facing release notes.
• There is a clear range: a tag, a date, or a commit SHA to diff from.
• The audience is users, not contributors (Conventional Commits already exists for the latter).

When NOT to use

• The repo has no user-facing surface (internal libraries, scripts) — a commit log is fine.
• The range covers months of work. Break it into smaller releases first.
• The user wants a marketing post — that's launch-tweet, not a changelog.

Approach

1. Get the raw commit list:

   git log <prev-tag>..HEAD --pretty=format:"%h %s%n%b" --no-merges
   

2. Group commits into three buckets, in this order:
   • Added — net-new user-visible capability.
   • Changed / Fixed — behavior that users would notice.
   • Internal — refactors, deps, docs (collapse into a single line at the bottom).
3. Translate from dev-speak to user-speak.
   • ❌ "refactor: extract validation middleware"
   • ✅ (skip — internal)
   • ❌ "fix: handle null in payment.processor"
   • ✅ "Fixed a crash when applying coupons to gift cards."
4. Drop noise. Typo fixes, README tweaks, CI tweaks, version bumps → cut.
5. Each bullet is one sentence, past tense, user perspective.
6. If a bullet needs more than one sentence, it deserves its own blog post — link out.

Output format

## v<version> — YYYY-MM-DD

### Added
- <bullet>

### Changed
- <bullet>

### Fixed
- <bullet>

### Internal
- <one-line summary>: deps bumped, tests added, docs polished.

Skip empty sections entirely.

Worked example

Input commits:

a1b2c3d feat: add CSV export to reports
e4f5g6h fix: correct rounding in monthly totals
1a2b3c4 chore: bump axios to 1.7.5
9z8y7x6 refactor: split UserService
5d4c3b2 docs: fix typo in README
abcdef0 feat: dark mode toggle

Output:

## v1.4.0 — 2026-04-30

### Added
- CSV export for any report — find it in the report toolbar.
- Dark mode toggle in Settings → Appearance.

### Fixed
- Monthly totals now round consistently with daily totals (off-by-1¢ on edge cases).

### Internal
- Dependency updates and a service refactor; no user impact expected.

Hard rules

• Past tense. "Added X", not "Adds X".
• One bullet, one sentence. If you need a second sentence, you're explaining implementation.
• Link to docs/blog if a feature needs context. Don't inline tutorials.

---

中文版

何时使用

• 用户在发布版本，需要面向用户的更新说明。
• 有明确的范围（上个 tag、某个日期、某个 SHA）。
• 受众是用户，不是贡献者（Conventional Commits 给后者用）。

何时不使用

• 仓库无用户访问面（内部库 / 脚本），commit 日志够了。
• 范围跨度几个月——先拆成小版本。
• 用户其实想要营销稿——那是 launch-tweet 的活。

步骤

1. 拿提交列表：

   git log <prev-tag>..HEAD --pretty=format:"%h %s%n%b" --no-merges
   

2. 分三组：
   • 新增（Added）——新功能。
   • 变更/修复（Changed/Fixed）——用户能感知的行为变化。
   • 内部（Internal）——重构、依赖、文档——折叠成一行。
3. 翻译成用户能懂的话。
4. 过滤噪声：错别字、CI 调整、版本号 bump → 删掉。
5. 每条一句话，过去时，从用户视角写。

硬规则

• 过去时。
• 一条一句。需要两句说明你在解释实现细节，删掉。
• 复杂功能链接到博客或文档，不要在 changelog 里写教程。