Ask HN: How do you handle release notes for multiple audiences?

While more automation certainly is useful, I find that auto-generating changelogs in this manner has a number of problems:

Auto-genertaed changelogs lack business-aware context about what is important. You get a big list of new features, but which ones are the most important to stakeholders? You have a few breaking changes, which are likely to have the most widespread impact? Without being judicious about what information is included, you risk overwhelming readers with line noise and burying important notes.

Some things go beyond the scope of a commit message - deployment nuance, interaction with other relases, featureset compatibility matrices. These are best summarised at the top level, they don't fit in individual disparate messages.

One of OP's motivations for starting this thread was to see how people tailor changelogs to different types of stakeholders; techincal vs non-technical, for example. This approach doesn't solve that problem. In fact, I think it's worse due to an additional side effect: the commits are now forced to do double duty; they must be useful commits for developers looking at code history, but now they also must be useful messages to be included in a changelog. While there is some overlap, it's hard to do both simultaneously. One must pick between writing good commit messages for the codebase & developers, versus writing a coherent changelog.

As a matter of personal taste, I think it looks lazy. Changelogs are a unique opportunity to communicate something important, they're written once and read by many. With a list of commits, myself and all other readers must now put in the work to find out what's relevant - it's disrespectful of others' time.

Whether you need a secondary set of release notes is almost purely a "marketing" decision, and should as much as possible be treated as such. Doing that is also usually way more effort (e.g. producing screenshots, etc.) than just writing plain release notes for a purse software engineer audience.

I think crafting good release notes (that go beyond automated release notes generated based on conventional commits, which are mostly good for bug hunting), is still a mainly manual and tedious process, though after the first few decent hand-crafted ones, the first draft can be handed off to an LLM these days.

Internal release notes:

* consisting of PRs merged since last release. (This is better than manually updating CHANGELOG. Do not allow direct commits to main w/o a PR.)

* internal audience is engineering, PMs, customer success & support, these do not leave the company.

* PRs can be examined for more context if needed. This is a good enough balance between noise & automation.

* If you use a working tracking system like JIRA or GitHub issues, join the PRs w/ the system to output priority and other labels (like Feature/Bug). This will help internal stakeholders quickly identify how important each line is. Sort by priority and/or group by labels.

External release notes:

* manually updated log of important changes, such as new features or other larger changes. These do not include all bug fixes.

* visible to customers.

* do not mention version numbers, only dates. You do not want to leak how often you release, or customers will start demanding release notes per version or dictating your release schedule.

When you fix bugs for customers, tell them what day/time the bug fix went live.

Obtaining set of PRs merged since last release is non-trivial, but doable.

I don't think it's worth having multiple versions. It's more important to have at least one well-written version.

What I've seen work well for a UI-centric service: Let a UX person craft the release notes and a product person edit/tweak them.

First sentence (after name on the product and version number) should be short deception what the product is. Then list of changes.