Yeah that pretty much describes every big companies release notes. I used to have manual updates in the Google Play store as I enjoyed seeing what was changing. But over time so many companies just started saying things like "Security fixes" and it became a waste of time even bothering to look at them.
And sometimes they do actually add a feature... but they'll mention it within the app itself despite the app updates not mentioning it. Or even more funny is how often I'll see a news article talking about the new feature, but then it never even gets mentioned in the release notes anywhere.
This should be illegal if auto-updates are enabled or eventual updates are forced. Not joking.
Nowhere else in society do we allow such self-serving laziness and unethical negligence (looking at you, purposely destroying backwards compatibility of APIs) at a professional level. Most other professions have steep legal consequences if they hide their actions or inactions.
Perhaps the perfect time to ask: why are release notes like this on the App Store? Are they a required field and this is the default? Does a popular tool use this value?
Not only nobody reads them, but Apple forces you to translate them into languages even less than nobody read. It'd be an improvement if they only required English text.
"Choose your own update notes adventure! Pick only one: A, B, or C.
A. The holidays are coming up and we've been busy planning a celebration of bug bashes and performance enhancements, so get merry and smash that update button.
B. Shorter days, longer nights, colder temps. You know what helps the Winter blues?
Instant gratification. Tap update, watch that progress bar fill up, and feel the dopamine flow.
C. Whoever made up the mistletoe thing was crazy. You know what's not? Updating your app."
Don't underestimate the effort a software developer will put forth to create mountains of complicated automation and scripts if it allows them to be lazy. And they see no issue with this. So why would they see an issue being accountable for yet another agile cycle.
While I'm morally tempted to do the same, many of the apps guilty of this are the major ones one uses, and as time goes by, I somehow find myself with less and less time on my hands, so I have to be selective with the things I want to do right and proper. Thus, by means of inaction, I indirectly contribute to the circle of enshittification, and there is no stopping it.
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.
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
I’m in a similar place with an internal tool. I have a two part changelog. In the first part, each release gets 50 words or less justifying its existence. This is ready to be copy pasted for management consumption. The second part goes into detail about what’s in the release, for technical people who care about those details.
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.
> 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?
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.
- The git commit log is the raw material. We try to have clean commits, but it's as messy as it is.
- This gets compiled into CHANGELOG.md at release time; we include all functionality and bugfixes, basically anything that any user or non-team dev might be interested or care about. But if some feature required multiple commits, we only include one line item for it. And if a feature gets reverted, we don't include both the feature and the reversion (that would be very confusing). This is for posterity.
- From the CHANGELOG we gather the "important subset" for the github release notes; this includes all features and major bugfixes, but only major API additions or changes. This has "see the CHANGELOG[link] for the full list of changes" at the bottom. This is for developers and users who follow us on github and are therefore more dev-savvy.
- From these release notes we produce the website release notes. This includes a complete list of new features, options, and commands, and important bugfixes (ones that a user might have experienced and would compel them to upgrade). But not any API changes unless it was a topline item for this release. This is for users and links back to the CHANGELOG.
- From the release webpage we pull highlights for social media, which link back to the release webpage.
We can always target different groups on social media with different subsets of functionality, but linking back up through the funnel leaves a trail of breadcrumbs for people who are more interested in the details.
At risk of getting thrown off the damn roof this is the problem I'm solving with my current product.
You've pretty much got the gist of it, the way we're going after the problem is producing internal notes rolled up from the code changes, and the main thing that changes as we move that communication from internal to external is frequency and delivery method.
We're still fairly early, but I think it's a mistake to think the contents of that communication should change. As soon as you get past the developers who wrote the code the primary thing people care about is customer benefit and how this work contextualizes into our goals, so we start there.
Internal comms comes out in internal channels (eg, Slack), and gets updated frequently (> 1x a week). As we bring that message out to customers we offer more self serve options (eg, hosted URL, embedded widget), and then only recommend pushing a notification once a month in the form of a recap.
(But you should still have a place that potential customers can see all the work your team is doing)
Would love to talk more on it, and thanks for brining this question up, very cool to see all the responses.
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).
We read through the release notes for our server software before installing it so that we can warn users about new functionality, disable functionality that's not approved, etc.
Maybe some don"t. But, when your "app" has a new release every other week, better put a reason why would I want to update (because for me: Updates = bugs and breaking changes).
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.
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.
My daily use software updates almost daily (web based app) They post almost no release notes. Update breaks your daily work flow, too bad. update completely changes the customer experience? Maybe a blog post at the end of the month. Release a new feature that nobody asked for: public change log entry with fanfare!
I would love every professional software to have a full release note for each update, as well as options to not have your web app update until you are ready for the changes to your flow.
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.
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.
for me it has varied based on the product type and scope, i.e release note for everyone like on a mobile app release or a SaaS platform, vs a tenant specific customized release. There are multiple ways to single source it, and now LLMs can help you out a bit.
If you just need a simple thing, query what you are releasing (from jira or whatever tracking system you are using) and package them up into categories of features/bug fixes and keep the release notes general.
if it's important to have an accurate curated set of release notes, create a field in your bug db for external release notes---leave those for tehncical product managers, support etc to edit as they want. THen you can have internal and external ones.
you always need to review for language and sensitive data, so human review (but again LLMs are helpful now fo this stuff too)
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.
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.
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.
* 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.
If you make use of something like git-cliff style formatting for the first line of your commit messages it can actually make some decent automated release notes that can be broken down into features, bug fixes, documentation, chores, etc...
I've found this to be pretty useful for my projects, and users can quickly get a list of what they care about for changes (usually the features part). Since it's pretty automated, the amount of effort also means that even if barely anyone reads them, it's not a huge waste of time. It's actually kind of made me write better, more useful commit messages as I know that the first line of the commit will actually be presented to the user.
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.
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"
Yeah that pretty much describes every big companies release notes. I used to have manual updates in the Google Play store as I enjoyed seeing what was changing. But over time so many companies just started saying things like "Security fixes" and it became a waste of time even bothering to look at them.
And sometimes they do actually add a feature... but they'll mention it within the app itself despite the app updates not mentioning it. Or even more funny is how often I'll see a news article talking about the new feature, but then it never even gets mentioned in the release notes anywhere.
This should be illegal if auto-updates are enabled or eventual updates are forced. Not joking.
Nowhere else in society do we allow such self-serving laziness and unethical negligence (looking at you, purposely destroying backwards compatibility of APIs) at a professional level. Most other professions have steep legal consequences if they hide their actions or inactions.
Perhaps the perfect time to ask: why are release notes like this on the App Store? Are they a required field and this is the default? Does a popular tool use this value?
The real answer is this: https://www.reddit.com/r/iOSProgramming/comments/1efubql/im_...
Not only nobody reads them, but Apple forces you to translate them into languages even less than nobody read. It'd be an improvement if they only required English text.
Meanwhile I see the most bizarre changelogs that I don't understand why Apple approves.
https://apps.apple.com/us/app/chime-mobile-banking/id8362152...
"Choose your own update notes adventure! Pick only one: A, B, or C.
A. The holidays are coming up and we've been busy planning a celebration of bug bashes and performance enhancements, so get merry and smash that update button.
B. Shorter days, longer nights, colder temps. You know what helps the Winter blues?
Instant gratification. Tap update, watch that progress bar fill up, and feel the dopamine flow.
C. Whoever made up the mistletoe thing was crazy. You know what's not? Updating your app."
This... also serves no useful purpose.
Don't underestimate the effort a software developer will put forth to create mountains of complicated automation and scripts if it allows them to be lazy. And they see no issue with this. So why would they see an issue being accountable for yet another agile cycle.
Rev number go up!
They're required for every version release and no one reads them anyway.
I read every single one. Any app that does this gets uninstalled and a nasty letter to software managers.
Well you're no fun, Sir...
While I'm morally tempted to do the same, many of the apps guilty of this are the major ones one uses, and as time goes by, I somehow find myself with less and less time on my hands, so I have to be selective with the things I want to do right and proper. Thus, by means of inaction, I indirectly contribute to the circle of enshittification, and there is no stopping it.
They forget always the "," between "bug" and "fixes".
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.
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
I’m in a similar place with an internal tool. I have a two part changelog. In the first part, each release gets 50 words or less justifying its existence. This is ready to be copy pasted for management consumption. The second part goes into detail about what’s in the release, for technical people who care about those details.
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.
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.
> 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?
really helpful, thanks for sharing!
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.
It's a funnel of sorts:
- The git commit log is the raw material. We try to have clean commits, but it's as messy as it is.
- This gets compiled into CHANGELOG.md at release time; we include all functionality and bugfixes, basically anything that any user or non-team dev might be interested or care about. But if some feature required multiple commits, we only include one line item for it. And if a feature gets reverted, we don't include both the feature and the reversion (that would be very confusing). This is for posterity.
- From the CHANGELOG we gather the "important subset" for the github release notes; this includes all features and major bugfixes, but only major API additions or changes. This has "see the CHANGELOG[link] for the full list of changes" at the bottom. This is for developers and users who follow us on github and are therefore more dev-savvy.
- From these release notes we produce the website release notes. This includes a complete list of new features, options, and commands, and important bugfixes (ones that a user might have experienced and would compel them to upgrade). But not any API changes unless it was a topline item for this release. This is for users and links back to the CHANGELOG.
- From the release webpage we pull highlights for social media, which link back to the release webpage.
We can always target different groups on social media with different subsets of functionality, but linking back up through the funnel leaves a trail of breadcrumbs for people who are more interested in the details.
At risk of getting thrown off the damn roof this is the problem I'm solving with my current product.
You've pretty much got the gist of it, the way we're going after the problem is producing internal notes rolled up from the code changes, and the main thing that changes as we move that communication from internal to external is frequency and delivery method.
We're still fairly early, but I think it's a mistake to think the contents of that communication should change. As soon as you get past the developers who wrote the code the primary thing people care about is customer benefit and how this work contextualizes into our goals, so we start there.
Internal comms comes out in internal channels (eg, Slack), and gets updated frequently (> 1x a week). As we bring that message out to customers we offer more self serve options (eg, hosted URL, embedded widget), and then only recommend pushing a notification once a month in the form of a recap.
(But you should still have a place that potential customers can see all the work your team is doing)
Would love to talk more on it, and thanks for brining this question up, very cool to see all the responses.
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).
No one read them so a single version is more than enough
We read through the release notes for our server software before installing it so that we can warn users about new functionality, disable functionality that's not approved, etc.
Maybe some don"t. But, when your "app" has a new release every other week, better put a reason why would I want to update (because for me: Updates = bugs and breaking changes).
This!
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.
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.
My daily use software updates almost daily (web based app) They post almost no release notes. Update breaks your daily work flow, too bad. update completely changes the customer experience? Maybe a blog post at the end of the month. Release a new feature that nobody asked for: public change log entry with fanfare!
I would love every professional software to have a full release note for each update, as well as options to not have your web app update until you are ready for the changes to your flow.
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.
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.
for me it has varied based on the product type and scope, i.e release note for everyone like on a mobile app release or a SaaS platform, vs a tenant specific customized release. There are multiple ways to single source it, and now LLMs can help you out a bit.
If you just need a simple thing, query what you are releasing (from jira or whatever tracking system you are using) and package them up into categories of features/bug fixes and keep the release notes general.
if it's important to have an accurate curated set of release notes, create a field in your bug db for external release notes---leave those for tehncical product managers, support etc to edit as they want. THen you can have internal and external ones.
you always need to review for language and sensitive data, so human review (but again LLMs are helpful now fo this stuff too)
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.
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.
A changelog.md file for users which is used to automatically create release messages.
If features need more explanation, we create a wiki page and link it in the release.
Sometimes we feel like there should be a changelog for devs but in the end git blame is used anyways.
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.
Release notes are read by apps stores approvers to determine reasons to reject your update. Better remain vague.
For npm ecosystem I use changesets.
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.
If you make use of something like git-cliff style formatting for the first line of your commit messages it can actually make some decent automated release notes that can be broken down into features, bug fixes, documentation, chores, etc...
I've found this to be pretty useful for my projects, and users can quickly get a list of what they care about for changes (usually the features part). Since it's pretty automated, the amount of effort also means that even if barely anyone reads them, it's not a huge waste of time. It's actually kind of made me write better, more useful commit messages as I know that the first line of the commit will actually be presented to the user.
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.