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

As per industry standards:

v1.4.18 - "Bug fixes and performance improvements"

v1.4.17 - "Bug fixes and performance improvements"

v1.4.16 - "Bug fixes and performance improvements"

I think a lot of it boils down to your goals with it, I'm personally very engaged with my user base and take pride in my communication and you may not value that over less work/more dev time. This is also for an internal tool but the audience is diverse (500+ devs, cybersecurity engineers, leadership, writers, etc), I stick with one set of release notes for a few reasons:

- One location, people who may fall into multiple categories (or none) don't need to check multiple places, users also know that all my communication will be via that page/they don't have to wonder if they're missing something

- As much as some detail doesn't matter to certain audiences, I find being able to give all the detail you want a user to know while maintaining readability to less technical audiences is a skill worth developing because the result is regardless of where your notes end up, the person will understand what's changed and why it matters

- Maintaining multiple versions leads to mistakes, at some point you'll leave out a detail to one audience that matters so letting the user mentally filter what they don't care about takes the onus to get it right 100% of the time off of you. I'll often categorize my changes by the section that had the change to help users with this.

- This is a personal preference and you touched on this one but it's just far less work, I've found it common in tech that people don't want to do things more than once or they'll automate it/look for shortcuts and this is no different. This isn't always a bad thing but getting release notes right means your users stay informed/use new features which is why we build them so I think it's worth putting my energy into doing it properly every time

For us it is relatively straightforward. Every release gets one single post. It always gets a title highlighting the most important change highlighting why people want to upgrade. This is followed by a short summary of which usecase is now supported by a change we did (either added feature or some enhancement). This is again followed by a detailed story on the items above and finally a granular list of security, interface changes, etc., pointing at the relevant ticket number containing for each change the full reasoning and history.

Mostly this is a manual effort on the textual bit. A PR is required to indicate whether something is worthy to be specifically mentioned in the release notes. The list of concrete changes is automated.

I use a phone app called 'transit' to find out where the buses are at any moment. It's a great app for a lot of reasons, but the reason I was drawn to it at first was their witty release notes.

As the author of an R package, my release notes are much drier and businesslike. The package is quite static, so releases are mainly bug fixes. I start each item with either 'Add' or 'Change', then I name the function, and then I supply a short descriptive phrase and end with a link to the github issue where where users can see why the change was made, and what the code differences were.

I realize that this is not an answer to the question, really, because all users of the R package are basically on an even footing, in terms of knowing the R language and the science that the package is intended to support. If there is something transferrable to the OP's use-case, I guess it is to be systematic and terse, and to use a fairly fixed way of writing (being aware that not all users have English as the first language).

I automate one changelog per project using git-cliff and conventional commits:

https://github.com/orhun/git-cliff

https://www.conventionalcommits.org/en/v1.0.0/

This changelog is copied into the release on github, or wherever the release is announced.

This was a discussion point at the WriteTheDocs conference this year, and lots of teams were managing multiple release docs: changelog (mostly automated and granular), then release notes for notifying customers, followed by feature specific announcement blogs, which get condensed to the notification feature in the app itself.

One of the things that stood out was the need for the docs teams to have visibility and early notice about what is going into a release. Some teams mentioned using slack emojis for markers to help review what is proposed for promotion for eg. another was the buy-in to treat these various docs as strict release requirements (will you be willing to block a release because the docs aren’t ready?)

Lots of LLM-driven tooling attempts, but the Ghostty one is the only one I remember reading publicly.

do you feel like more than one set is needed?

No. The release notes are for the end user.

There should be a separate changelog for technical users. This documents changes to the software including things that are invisible to users. For example, adding some unit tests wouldn't be in the release notes but it would be in the changelog.

Stakeholder comms is an entirely separate, but equally as important, thing. That should include information about impact the release is expected to have, what dependencies it impacts, and who gets the credit for work in the release.

No one read them so a single version is more than enough

Our release notes are all internal.

Each user story has separate fields with summary information, testing notes, and technical information for developers. The release process pulls the information from the linked user stories into an Excel spreadsheet, and the non-technical users just ignore that column.

Most stakeholders only need to hear about major milestones. They don’t get release notes. They get weekly or monthly memos on what the department is accomplishing.

Unless you’re developing open source or developer APIs/SDKs, end users don’t care about release notes. The KB needs to get updated, and meaningful feature improvements get announced in newsletters or blog posts every N weeks. A good customer experience team will take care of this based on raw release notes, and also notify customers who reported bugs when those bugs are fixed.

Engineers working on the product get raw release notes.

Engineers integrating the product ideally get something edited a bit to be maximally useful when working out how to upgrade — Django’s release notes are something to aspire to.

The change log for developers/administrators/etc. comes from the Git history. We use conventional commits. Breaking changes in the semantic version of a subcomponent means, "If you're operating this service, you can't just bump the container version and keep your current config.

The change log for end users comes from the JIRA board for the release, looking at what tickets got closed that release cycle, and it usually requires some amount of human effort to rewrite.

Conventional commits along with Release Please: https://github.com/googleapis/release-please-action

I've used feat/feat(pub):, fix/fix(pub):, etc before to automatically separate changelogs into internal/public.

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.

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

For npm ecosystem I use changesets.

Release notes are read by apps stores approvers to determine reasons to reject your update. Better remain vague.

I’ve always gone for a document that expands fractally - that is to say, the title is clear, the opening paragraph gives an overview that a stakeholder would want, the following paragraphs give top level detail for a quick skim/end users, and then you delve into the detail of each feature/fix/etc.

The first sentence should inform of any breaking changes or major (e.g. security) fixes. For instance:

We are pleased to announce the release of version 2.2.1, which includes several fixes for major issues, includes one change which will require action on your part, 36 bug fixes, 12 enhancements, and the new combine harvester feature.

And then you drill into the top level. Also, categorise, it helps people find stuff.

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.

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.

If there is an audience for release notes I haven't seen anything better than just committing entries to a pre-release folder as you change things and have release automation compile the folder into the actual release notes. Python and many other large projects handle it like this: https://github.com/python/cpython/tree/main/Misc/NEWS.d/next (The release notes for major releases are crafted manually)

On the other hand, for many projects you can probably skip release notes: nobody will read them. Even fewer people would read automatically generated changelogs: don't bother setting it up. Releasing instead of deploying from master also implies you took more care than usual, did you? Commit messages make sense for cohesive changes, are they? Didn't think so.

Hardly anyone reads them, and unless you are a dev tool which might require more depth, just give a bullet point list of changes. Don’t overthink it, nobody cares.