Release Notes People Can Act On In short: A generated commit log is a receipt, not documentation. The reader is a developer under deadline who wants one question answered: what do I have to do? tells a consuming developer nothing. They do not know what changed for them, whether their build will break, or whether they can skip this one. Write for that reader. Four sections, in this order The order is the point. Breaking changes first, always. 1. Impact summary One paragraph at the top. Risk level and required action. v12.0.0 — action required for users > > This release removes the deprecated input and adds a data grid. > If you bind anywhere, run — the > included migration handles it automatically. If you do not use , > this is a drop-in upgrade. Estimated effort: 10 minutes, mostly reviewing the migration's diff. That last line is worth including on every release. A tech lead planning a sprint needs a number, and giving them one is the difference between the upgrade being scheduled and being deferred. 2. Breaking changes Front and centre, with the exact fix. 🚨 Breaking changes removed from > > Deprecated in v11.4.0. Replaced by , which accepts a translation key. How to upgrade — automatic: If the migration cannot reach your code (inline templates in files): Verify: Every breaking change gets four things: what changed, why, the automated fix, and the manual fallback. The is small and disproportionately appreciated — it lets someone confirm they are done. 3. New features, with the reason to care Consumer teams have their own roadmaps. Give them a reason to prioritise your release. ✨ New with built-in CSV export > > Replaces the hand-rolled export logic several teams have written. Sorting, > column resizing, and export are included and accessible. > > > > The farmer portal removed 180 lines of export code adopting this. That last sentence does more work than the feature description. "Another team deleted 180 lines" is concrete. 4. Deprecations — the early warning ⚠️ Deprecated — removal in v13.0.0 (planned Q2 2027) → use . > The old token now aliases to the new one and will keep working until v13. → use . > Migration guide: [link]. A schematic is available now: . Note the schematic is available at deprecation time , not at removal. Teams can migrate today, on their own schedule, which is the whole point of the previous lesson. Generate the skeleton, write the top or will turn conventional commits into a changelog. That output is a good raw material and a bad release note. The workable split: Automated Written by a person --- --- The commit list, grouped by type The impact summary The version number (from Chapter 8's API diff) Migration instructions Contributor list, links, dates Effort estimate The API diff table Why a feature matters Chapter 8's API diff can seed the breaking-changes section, since it already knows exactly what broke: The placeholder is deliberate. It makes the missing human work visible rather than letting a machine-generated list ship as if it were documentation. Anti-patterns Do Don't --- --- Breaking changes at the top Bury them under "Features" The exact command to run "Update your usage accordingly" An effort estimate Leave planning to guesswork Name what replaces a removal Remove without a replacement Say who benefits from a feature List the commit subject One note per release A single 4,000-line CHANGELOG.md Link the migration guide Assume people will find it That last row about is worth stating plainly: a single accumulated file is fine as a historical record and useless as a communication. Publish per-release notes where consumers actually look — the release page, and a message in the channel where they work. "But I thought the changelog was generated automatically" It is, and that is genuinely useful — nobody should hand-maintain a version history, and conventional commits give you an accurate, complete record for free. The gap is that a generated changelog answers "what did the library team do?" and the reader is asking "what do I have to do?" Those are different questions, and only one of them is answerable from commit messages. Take a real generated entry: Everything there is accurate. Now try to act on it. Does "correct token reference" change how the card looks — do I need to re-approve baselines? Does the grid export replace the code I wrote last quarter? "statusText removed" — is there a replacement, is there a migration, how long will this take? Not one of those is answerable, because the commit author was describing their change to their team, not to you. There is a deeper reason this cannot be fixed by writing better commit messages. Impact is context the author does not have. The developer removing does not know which of twenty applications use it, whether the migration covers their inline templates, or what it will cost them. Determining that requires looking outward, at consumers — which is a separate act from making the change. Generated changelog Written release not…