Changelog

Draft a release changelog

Overview

Turn the commits since the last release tag into a docs/CHANGELOG.md entry: concise user-facing bullets, contributors credited, in the house style.

Core principle: always draft first and show the user — apply to docs/CHANGELOG.md only after they accept. The user asked for a draft to review, not an automatic edit.

Workflow

1. Get the target version from the request (e.g. 0.42.0) and find the range:

   git tag --sort=-v:refname        # newest tag first
   

   • Target is not yet a tag (drafting an unreleased version, the usual case) → range is <newest-tag>..HEAD.
   • Target is an existing tag → range is <tag-immediately-before-it>..<target-tag>.

2. List commits with authors + emails (email carries the GitHub handle):

   git log <range> --format='%h|%an|%ae|%s'
   

   For a commit whose body matters (root cause, what actually changed), read it:

   git show -s --format='%s%n%b' <hash>
   

3. Derive contributor handles from the author email:

   • NNN+handle@users.noreply.github.com → @handle (e.g. 175231748+linkmodo@... → @linkmodo).
   • Other emails: reuse the handle that person already got in earlier docs/CHANGELOG.md entries (git log/grep the file); ask the user if unknown.
   • Known map: Paul Glover=@paulglover, jboneng=@jboneng, Robin/light-sntchr=@light-sntchr, Henning Ullrich=@hullrich.
   • marcinz606 is the owner — never credit them.

4. Drop housekeeping commits — no changelog line for: README/badge edits, changelog typo fixes, merge/revert/"rogue file" cleanups, pure internal log-noise fixes, version bumps.

5. One bullet per feature, never one per commit. A feature built over several commits — the feature, then its fixes, follow-ups and polish — gets a single bullet describing the shipped state. Fold anything the user should know into that bullet and write no extra Fix: or Change: line: a bug that never reached a build is not news. Group the range's commits by feature first, then write. Check every candidate bullet against the range's other bullets and the entries already in the section, not only the new commits.

   The same holds for a fix to an existing panel or control touched more than once in the range: one bullet naming the end state, not a line per commit.

6. Check what's already documented — the top ## section may already hold a few entries. Merge into it; don't duplicate.

7. Write one bullet per feature in the house style (below), grouped New → Change → Fix.

8. Show the draft in the reply. On approval, insert into docs/CHANGELOG.md under the target ## X.X.X heading (create it if absent), merged with any entries already there.

9. Set VERSION to the requested version — the repo-root VERSION file holds the bare number (0.56.0, no v, trailing newline). Write it in the same change as the accepted changelog entry.

House style

(Established preference — see the user's changelog-style memory.)

• One entry per feature, not per commit — the shipped state, with its in-cycle fixes folded in.
• One line per entry, no explanatory paragraphs: Prefix: **bold lead** — terse clause naming what was done. Skip the failure-mode/root-cause narrative even on fixes. The long multi-sentence bullets in old sections are not the target.
• Prefix each with New: / Change: / Fix: (use Change/Fix: if genuinely both). Group in that order.
• No PR/issue numbers ((#604)) — user-facing notes, not a dev index.
• US "color" in prose, matching the UI labels (Color Negative, colour spellings were swept out in 0.50.0).
• Plain, factual, non-salesy — it's an open-source project. No marketing framing, no dunking on other tools.
• Credit code/idea contributors with a trailing @handle; never credit whoever merely requested or reported it.

Example (0.41.0, accepted)

- New: **Manage Database…** — dialog to inspect and clear stored data; Clear Saved Edits or Reset Everything, both guarded. @linkmodo
- Change: **Bottom toolbar streamlined** — zoom slider removed, GPU/CPU toggle moved to the overflow menu, tooltips on every item; Before/After and Peak Flat are now mutually exclusive and survive rotate/flip. @linkmodo
- Fix: **Saved export destination restored on reopen** — the Folder mode no longer resets to "Subfolder of source". @paulglover

Gotcha

git log/git show output is piped through the RTK hook, which truncates long output and garbles it. If a log looks cut off, rerun with rtk proxy git … to bypass the filter, or dump to a file and open it with the Read tool (Read is unhooked). Trust exit codes over rendered text.