How to automate release notes: who is actually reading them

Generating release notes from commit messages produces a document that is accurate, complete, and read by nobody. It lists everything that changed, which is precisely what no reader wants, and it is written in the vocabulary of the people who made the changes rather than the people affected by them.

The problem is not extraction. It is that "release notes" names three different documents for three different audiences, and automating the generation of one undifferentiated list means producing something that serves none of them well.

What we'll cover

• Three documents, one name
• Why commit messages are the wrong source
• Capturing the note at the right moment
• Building it with CodeWords
• Deciding what is worth announcing
• Writing for a customer
• Breaking changes deserve their own treatment
• Where each document should live
• Making it survive
• Limits worth knowing about
• What to build first
• Frequently asked questions

Three documents, one name

The technical changelog is complete, dated, and dull by design. Its readers are integrators and support engineers looking for a specific change, and completeness is its whole value.

The customer announcement is selective, written in product terms, and covers a handful of things. Its job is to make somebody use a feature they did not know existed.

The internal release note tells support, sales and customer success what changed and what customers will ask about. It is the one most often missing and the one with the clearest return.

They have different rules. The changelog must include everything; the announcement must exclude nearly everything; the internal note must predict questions.

Generate all three from one source of structured notes, rather than writing one document and hoping it serves everybody.

Say which is which. A page titled "Release notes" that is actually a changelog trains customers not to read it.

Why commit messages are the wrong source

They describe the change, not the effect. "Refactor the queue consumer" is accurate and tells a customer nothing.

They are written for reviewers who have the context, which is exactly the context the reader lacks.

Conventional commit prefixes classify the work, not the user impact, so feat includes both a major capability and an internal helper.

Noise dominates. Merges, reverts, dependency bumps and formatting are the majority of commits in most repositories.

Nothing marks significance. The one change customers care about looks identical to forty that they do not.

Pull request titles are better and still insufficient, which is why the note needs to be captured deliberately rather than derived.

Capturing the note at the right moment

Ask at the pull request, in a template field, while the author still remembers why the change matters.

One sentence describing the effect on a user, or an explicit "no user-visible change", which is a valid and common answer.

Mark the audience — customer, integrator, internal — so the three documents can be assembled without a second pass.

Flag breaking changes explicitly, since inferring them reliably is not possible and the cost of missing one is high.

Keep it optional but visible. A required field produces filler; an obvious empty field that appears in a weekly report produces notes.

Anything unmarked goes to the changelog only, which is the safe default and removes the pressure to classify everything.

Building it with CodeWords

CodeWords connects to more than 3,000 integrations, so the repository, the tracker, the documentation site and your announcement channels can meet in one automation.

1. Open CodeWords and start a new automation.
2. Describe what should happen in plain language to Cody, the automation builder: which sources, the three audiences, and where each document goes.
3. Authorize the connections — the repository, the tracker, and the destinations for each document.
4. Describe the exceptions: a security fix, a breaking change, anything embargoed until a launch date.
5. Generate a draft for the last three releases and compare it against what was actually sent.

You describe the outcome; Cody builds it, connects it, and deploys it. The free plan covers light use, with Pro at $39 per month and Business at $100 per month as usage grows; details are on the pricing page.

Deciding what is worth announcing

Does it change what somebody can do? If not, it belongs in the changelog and nowhere else.

Would a customer act on it — try something, change a setting, stop a workaround? That is the test for the announcement.

Does it resolve something people complained about? Those are the highest-value items and they are systematically under-announced because they feel like admissions.

Three to five items maximum, since an announcement listing twenty things communicates that none of them matters.

Group the rest. "Plus a number of smaller improvements and fixes" with a link to the changelog is honest and sufficient.

Silence is an option. A release with nothing worth announcing should produce a changelog entry and no announcement.

Writing for a customer

Lead with what they can now do, not with what was built.

Use their vocabulary, which means the words in your interface rather than the words in your codebase.

Say who it affects, since most changes are relevant to a subset and telling everybody wastes most of the attention.

Include the one thing they need to do, if anything — a setting to enable, a version to upgrade.

Show it. A screenshot or a short clip outperforms any amount of description for an interface change.

Have a person edit before sending. Generated prose reads as generated, and this is the document where that is most damaging.

Breaking changes deserve their own treatment

Announce before, not with. A breaking change appearing in release notes on the day it ships is a support incident.

Say precisely what breaks and what the symptom looks like, so somebody can tell whether they are affected without reading code.

Give the migration path in the same message, since a breaking change without one generates a ticket per affected customer.

Name the deadline and repeat it, with the count of affected consumers where you have it.

Reach affected customers directly, not only through a public page, because the people who need this are exactly the ones not reading your changelog.

Never bundle it with feature announcements, where it will be skimmed past.

Where each document should live

Generation is half the job; the other half is that each of the three documents has a different natural home, and putting them in the wrong place is why they are not read.

The changelog belongs on a stable, linkable page, ordered by date, with every entry addressable so support can send somebody straight to it.

The customer announcement belongs where customers already are — in the product, in the email they already receive, not on a page they would have to remember to visit.

The internal note belongs in the channel support and success already read, not in a wiki page that requires somebody to go and look.

Make the changelog machine-readable as well, since integrators will want to subscribe rather than check.

Keep permanent links stable. Release notes get linked from support tickets and community posts, and a reorganisation that breaks those is costly in a way nobody notices for months.

Date everything visibly, because the most common question about a change is when it happened rather than what it was.

Making it survive

Handle the release with no notes by generating the changelog and skipping the announcement rather than sending an empty one.

Make generation idempotent, since a re-run should not produce a second announcement.

Respect embargoes on anything tied to a launch date, which is the failure that causes real trouble.

Keep security fixes out of automatic announcements until whoever owns that decision has looked at them.

Report the outcome: items captured, items marked customer-facing, and pull requests merged with no note at all.

Limits worth knowing about

Generated prose needs editing, particularly for the customer-facing document where tone carries most of the meaning.

Inferring user impact from a diff is unreliable, which is the argument for capturing it at the pull request instead.

Release cadence shapes the format. Continuous deployment makes "the release" a fiction, and the notes should be organised around features rather than versions.

Screenshots cannot be generated as part of this, so the announcement will always need a human step for interface changes.

Translation multiplies the editing cost, not just the generation cost, which is worth knowing before promising localised notes.

What to build first

The internal release note for support and customer success: what changed, who it affects, and what customers are likely to ask. It is the document most often missing, it needs no editorial polish, and it prevents the specific failure where a customer knows about a change before the person answering their question does.

Two habits make the difference. Capture the user-facing sentence at the pull request rather than trying to infer it later, since the author knows it then and nobody knows it afterwards. And let a release produce no announcement at all when there is nothing worth saying, because an announcement that lists twenty trivial changes teaches people to stop opening them.

Frequently asked questions

Why do generated release notes go unread?

Because they list everything that changed, which is what no reader wants, in the vocabulary of the people who made the changes rather than the people affected by them.

What are the three different documents?

A complete technical changelog for integrators and support, a selective customer announcement covering a handful of things, and an internal note telling support and sales what customers will ask about.

Why are commit messages a bad source?

They describe the change rather than its effect, they assume reviewer context, and noise — merges, reverts, dependency bumps — dominates. Nothing in them marks which change actually matters.

Where should the user-facing description come from?

A field in the pull request template, filled in by the author while they still remember why the change matters, with an explicit "no user-visible change" as a valid answer.

How many items belong in a customer announcement?

Three to five. An announcement listing twenty things communicates that none of them matters. Group the rest with a link to the changelog.

How should breaking changes be handled?

Announced before they ship, never bundled with features, with the precise symptom, the migration path, a repeated deadline, and direct contact with affected customers rather than only a public page.

Should fixes to things people complained about be announced?

Yes, and they are systematically under-announced because they feel like admissions. They are usually the highest-value items in the document.

Does continuous deployment change this?

It makes "the release" a fiction, so organise the notes around features rather than version numbers. The three-audience split still holds.

Where should release notes actually be published?

Three places: the changelog on a stable, addressable page that support can link into; the customer announcement where customers already are, in-product or in an email they already get; the internal note in the channel support and success already read.

Why do stable links matter for release notes?

Because they get linked from support tickets and community posts for years. A reorganisation that breaks those links is expensive in a way nobody notices for months.

What should happen to pull requests merged with no note?

They go to the changelog only, which is the right default. Report the count weekly though — a high proportion usually means the field is in the wrong place rather than that nothing user-visible shipped.

Related reading

• Automating a weekly team digest
• Automating pull request reviews
• GitHub and CodeWords