Release notes for users who don't read commit logs, and why month two is the hard one

Say you maintain a small open-source library on your own. A few hundred people depend on it, most of them are not going to read your commit history, and once a month you owe them a short "what changed and what do I need to do" note. Writing the first one is easy. The second one is where maintainers quietly contradict themselves.

I build Maildoer, an email assistant, and this post ends with how it handles the month-two problem. Most of it, though, is the template and checks I'd use with any editor.

Start from the reader's question, not the diff

A commit log answers "what did the maintainer do?". Users want three other things:

1. Do I have to change anything?
2. Is something I rely on going away, and when?
3. Is there anything new worth trying?

So sort every merged change into one of four buckets before you write a sentence:

• Action required: breaking changes, renamed options, new minimum versions.
• Heads-up: deprecations, with the version or date they'll be removed.
• New: features someone might actually use.
• Fixed / internal: bugs and refactors. One line each, or one grouped line.

Anything that doesn't fit a bucket probably doesn't belong in user-facing notes at all.

A template that stays short

## v2.4.0 (month)

### Do you need to do anything?
- [Yes/No]. If yes: one sentence per change, with the exact old -> new name.

### Coming up
- `oldOption` is deprecated and will be removed in v3.0 (planned: [month]).
  Use `newOption` instead.

### New
- One line per feature, with a link to the doc section.

### Fixed
- Grouped: "Five fixes around timezone parsing (#212, #215, #219...)."

Keep the "Do you need to do anything?" heading even when the answer is no. "No" is useful information and people learn to look for it.

Why month two goes wrong

Month one's notes made promises. Month two is written from a new diff, so it's easy to forget them. The usual mistakes:

• The deprecation date moves without a word. Month one said oldOption goes away in v3.0, planned for March. Month two's notes say "removed in a future release", and users who planned around March lose trust.
• Things get announced twice. A feature that shipped behind a flag last month gets announced again as new when the flag is removed.
• A workaround disappears. Month one told users to pin a dependency until a fix landed. The fix lands in month two, but the notes never tell them they can unpin.
• Tone drift. Month one used "Action required"; month two says "Breaking". People scanning for the old heading miss it.

The tool-free fix is a tiny "open promises" list you carry forward at the top of your draft each month:

Open promises
- oldOption removal: v3.0, planned March
- Users told to pin parser <1.8 until #230 is fixed
- Flagged feature: streaming mode (flag: STREAM_BETA)

Before publishing, every line in that list either appears in the new notes (kept, changed with a reason, or closed) or stays on the list for next month. Nothing silently drops off.

A brief you can hand to anyone

Whether you're asking a co-maintainer, a contributor, or a tool to draft the notes, this brief works:

Attached: the list of PRs merged since v2.3.0 and last month's release notes. Sort the changes into Action required, Coming up, New and Fixed. Use the same headings as last month. Check last month's "Coming up" and pinning advice and say explicitly what changed for each. Keep it under 250 words, plain English, no internal refactor detail.

Where Maildoer fits

This is the kind of job where remembering last month matters more than writing well. Maildoer doesn't read your month-two email as if it were the first one. It connects it with your earlier emails, so last month's deprecation date, the pinning advice and the flagged feature are taken into account when it drafts the new notes. If a draft gets something wrong, you reply with one line ("we pushed v3.0 to April, say why") instead of re-sending everything.

Checklist before you publish

• Every change is in exactly one bucket.
• "Do you need to do anything?" is answered, even if the answer is no.
• Each open promise from last month is kept, changed with a reason, or closed.
• No feature is announced as new twice.
• Headings match last month's wording.

If you want to try the brief on a real changelog, Maildoer works by email: send it to [e-mail]. Each address starts with 100 credits. Details at https://maildoer.com.