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

I’m French but… there isn’t a comma, is there? “Fixes” is the main noun, “bug” qualifies the noun. “Fixes of bugs” or “bugfixes” like “weekday” or “storm trooper”. Whether there is a space or not depends on lexicalization, ie whether it feels like one concept. Bugfix is a single concept but “snow patrol” is two; and modern compounds tend to be two separate words, so “bugfix” is only joined in technical environments, maybe not for the broader audience.

Joke lost in translation. He's implying those who engage in these types of nonsense release notes often add bugs instead of fixing them.

> You get a big list of new features, but which ones are the most important to stakeholders?

I worked for one startup with one major customer who was really skeptic of investing further because of stability problems, feature delay problems, and lack of transparency. Along with a complete list of changes that gave them insight into how we prioritised between stability and feature development, I wrote a human summary of what this meant — experiments, summaries of statistics, summary of most important changes to business logic.

Writing personally to your stakeholders does not exclude being systematic, and vice versa.

> As a matter of personal taste, I think it looks lazy.

That’s funny, because I find the lack of automation to be the lazy choice. Forgetting to add to the changelog because the requirement is checked by humans, or because single commits fix things below some bar of noteworthiness that is entirely subjective and driven by lack of structure. Not writing commit messages worth putting in release notes (fix sht, asdasdasd, etc.)

> 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.*

When I migrate software, I’m very interested in the complete picture. I’ll ask my AI agent to go over the links in the changelog and summaries for me what are the breaking changes and what manual steps do I need to take. Having them in human-readable form ahead of time would be nice.

Since git-cliff has different sections, I can skip changes to documentation. Because of SemVer, I know if there’s something breaking.

I like your idea of an additional human summary, that does definitely help.

> That’s funny, because I find the lack of automation to be the lazy choice.

Automation is cheap these days. Many automations make things that exceed human ability, but this isn't one of those cases. You'll get something good-enough, but not great. Perhaps that's what your organisation has time and budget for, in which case your use of automation makes sense, but if we're trying to make the best audience-tailored summaries of software releases with specific purpose, the strategy falls short.

> Forgetting to add to the changelog because the requirement is checked by humans,

Individual developers definitely can, which is why you must also have organizational process. If a valid changelog checked by a release manager is a requirement for a software release, it can't be forgotten.

> fix things below some bar of noteworthiness that is entirely subjective and driven by lack of structure. Not writing commit messages worth putting in release notes (fix sht, asdasdasd, etc.)

I'm curious about the implication of insignificant commits coming from a lack of structure. I think it's entirely normal to have single commits fix something innocuous. If there's a typo in one file, you wouldn't fix it as part of creating a feature, because that's work outside the scope of the feature. So it would have to be in its own commit, or alongside other similar refinements. And those examples are indeed unacceptable commit messages that would not make it through code review in any serious shop, but I get what you mean, and it's part of my point: developers are supposed to write commit messages for developers, and the needs of developers are different to the needs of people reading a changelog, so it's only natural that the text should be changed for the different audience.

> I’ll ask my AI agent to go over the links in the changelog and summaries for me what are the breaking changes and what manual steps do I need to take.

I really think this is backwards and exactly the thing I was advocating against. The changelog you have is so large and poorly-structured that you need to use an AI to summarise it for you, and gather the information that should have been in the changelog in the first place. If that needs to be done to make the changelog useful, clearly its original state is deficient?

> Automation is cheap these days. […] valid changelog checked by a release manager

If affirmation is cheap, why hire humans to sit and manually validate if a text file was updated? Maybe you have a lot of cheap labor or a lack of automation experts.

> The changelog you have is so large and poorly-structured that you need to use an AI to summarise it for you

https://terranix.org/news-2025-11-09_website_renewal.html

Not really that long and poorly structured, no.