For example: • technical version for developers • simplified version for end users • something more high-level for stakeholders etc…
In my current position I’ve seen a plethora of different ways teams, and even the company I currently work for, go about this.
What I’ve seen: 1. paste raw GitHub changelogs into customer emails (highly wouldn’t recommend if you’re currently doing this ) 2. manually rewrite the same update multiple times for each audience 3. skip release notes entirely because it’s too much work
So I guess my question is: How do you or your company currently go about handling more than one set of release notes, and do you feel like more than one set is needed?
Would love to hear what’s working (or not working) for you, and if you found any tools that help mitigate this issue.
v1.4.18 - "Bug fixes and performance improvements"
v1.4.17 - "Bug fixes and performance improvements"
v1.4.16 - "Bug fixes and performance improvements"
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.
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.
Deleted Comment
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.
Rev number go up!
- 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
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.
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.
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.
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.
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.
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).