I always use changelogs and try and link all changes to a pr. I don’t expect people to have to troll through dozens of individual per release notes. Why this has become a lost art is very mysterious to me unless it’s just laziness?
From working in mobile release pipelines, my experience with release notes was that the app stores (esp Apple) would nitpick release notes and hold up releases on a regular basis, so we went to generic release notes to avoid being blocked at approval on the Apple side. Pretty good example of a reverse incentive.
The author thinks the changelog is important and that their customers should read it, even going as far as adding it as a forced pop-up. Arguably, that’s quite a hostile form of changelog.
It’s great to have changelogs available but your customers absolutely don’t care about them, especially if they are not corporate customers. The article author has a lot of pride in each release: genuinely a wonderful thing, but not anything that is relevant to the person at the other end.
That’s why so many apps on the App Store have change logs that say something like “Thanks for using our app.” They wouldn’t even release a changelog if they weren’t forced to do so by the platform and their customers’ devices update in their sleep. They’d never see a changelog even if a detailed one existed.
The NetBSD developers keep a great CHANGES document up to date with what’s new overall, and even categorize it by architecture and machine when appropriate.
Want to know what changed between 10.1 and 11? Or 10.0 and 10.1? It’s all right there, summarized by the people who did the work.
I have a slightly different take on the loss of changelogs, although I agree with the version in this post.
My gripe[0] is developers using GitHub’s “releases” feature in lieu of a CHANGELOG.md. This feels particularly pertinent in light of GitHub’s recent performance woes.
Changelogs are really difficult to do properly. The concept of a "release" is fuzzy in a world of continuous deployment, and feature flags and experiments mean that different customers are seeing different features. The release of the client that can support the feature is often very divorced from the enablement of the feature. This is not a new phenomenon and has been something we struggled with way back in 2013 in my first SaaS job. Even if you do have a defined set of changes, the way modern software releases work means that the changelog is often the only reason to collect and document those all in one place, and not always a sufficiently compelling one to justify gathering and coordinating this information across teams in a large organization.
Anyway, time to go go see if Claude's done drafting that changelog I asked it to do...
It may be difficulty to do properly but then we shouldn’t throw our hands up and do nothing instead? Surely we can come up with a better practice better then filling the release form’s required details field with “Bug Fixes and performance Improvements” every single release?
Here’s a quick skimmed list of iOS apps I see doing this currently:
Carvana Cash App IMDB Kick Turo Twitch Instagram Prime Video
I’ll stop now as it’s nearly every app. Even Apple’s own apps do this— directly from the company who controls the UI of the app store and the developer experience of filling out the form with placeholder messages
It depends. For stuff like npm packages, where the downstream consumers have to make a conscious decision about whether to adopt the update or not, I absolutely think it's worth getting it right, especially for major version bumps. I myself am the user of an open source code gen tool that does not have comprehensive changelogs, and it makes me want to tear my hair out because we can never be confident when upgrading whether or not we're going to end up with changes that will break our workflows or our customers' workflows.
But for consumer apps, honestly, maybe not? Even at companies that do good consumer changelogs, they're generally considered marketing content. Other posters in this thread made the points that most people updating consumer apps are not even going to see the changelog message, and that app stores have effectively punished companies for providing detailed changelogs by holding app store releases over them.
And given that for larger companies so many of them are actually controlling their feature releases on the backend and not on the client side (you might add the capability for a feature on the client months before you actually set the rollout to 100%), trying to convey those updates in the client-side changelog can be hard to do in a way that consumers will understand and can often generate a lot of confusion and support tickets. After all, we don't expect a changelog entry every time a website updates, and I feel like every day mobile and desktop apps are getting closer and closer to that category.
Well yeah, it's obvious that companies love the "anything goes, no expectations" update model of websites and want to apply it to apps as well. I just don't think this is in the interest of users.
As an exteme example, we've had the situation several times now that a useful app that was maintained by a single person was eventually sold to some adware or malware company - who quickly pushed an update to stuff the app full of ads or do worse with it.
This only works because of the "ask no questions and accept the auto update" standard the industry established.
In the interest of openness and honesty to the user, that would be more reason to document those preparations in the changelog, so users know what to expect later on, if more features are activated.
Who needs changelogs if you can have animated mystery buttons and "look at our new feature!" overlays instead that pop up at the worst possible time and cannot be read again once closed?
I have stopped trusting automatic software and operating system updates, they take away useful features or break functional user flows or introduce unwanted AI slop too often. So I am very much back in the boat of software needing to justify an update for me to install it.
Just the usual symptoms of a profession which was never regulated properly, compared to an engineering profession. So anyone could drag it around however they please. Look this shiny thing I made, this is much better than the competing not so shiny things we use daily. You are a peasant not using the most shiny thing on planet earth, this is the new epoch.
Do we need this? Nah. Do we need this horrible abstraction over a zero complexity thing? Suuuure.
And this will lead to horrible issues later on. This is just another symptom.
I always use changelogs and try and link all changes to a pr. I don’t expect people to have to troll through dozens of individual per release notes. Why this has become a lost art is very mysterious to me unless it’s just laziness?
From working in mobile release pipelines, my experience with release notes was that the app stores (esp Apple) would nitpick release notes and hold up releases on a regular basis, so we went to generic release notes to avoid being blocked at approval on the Apple side. Pretty good example of a reverse incentive.
The author thinks the changelog is important and that their customers should read it, even going as far as adding it as a forced pop-up. Arguably, that’s quite a hostile form of changelog.
It’s great to have changelogs available but your customers absolutely don’t care about them, especially if they are not corporate customers. The article author has a lot of pride in each release: genuinely a wonderful thing, but not anything that is relevant to the person at the other end.
That’s why so many apps on the App Store have change logs that say something like “Thanks for using our app.” They wouldn’t even release a changelog if they weren’t forced to do so by the platform and their customers’ devices update in their sleep. They’d never see a changelog even if a detailed one existed.
The NetBSD developers keep a great CHANGES document up to date with what’s new overall, and even categorize it by architecture and machine when appropriate.
Want to know what changed between 10.1 and 11? Or 10.0 and 10.1? It’s all right there, summarized by the people who did the work.
I have a slightly different take on the loss of changelogs, although I agree with the version in this post.
My gripe[0] is developers using GitHub’s “releases” feature in lieu of a CHANGELOG.md. This feels particularly pertinent in light of GitHub’s recent performance woes.
0: https://hugotunius.se/2024/01/20/stop-using-github-releases....
Changelogs are really difficult to do properly. The concept of a "release" is fuzzy in a world of continuous deployment, and feature flags and experiments mean that different customers are seeing different features. The release of the client that can support the feature is often very divorced from the enablement of the feature. This is not a new phenomenon and has been something we struggled with way back in 2013 in my first SaaS job. Even if you do have a defined set of changes, the way modern software releases work means that the changelog is often the only reason to collect and document those all in one place, and not always a sufficiently compelling one to justify gathering and coordinating this information across teams in a large organization.
Anyway, time to go go see if Claude's done drafting that changelog I asked it to do...
It may be difficulty to do properly but then we shouldn’t throw our hands up and do nothing instead? Surely we can come up with a better practice better then filling the release form’s required details field with “Bug Fixes and performance Improvements” every single release? Here’s a quick skimmed list of iOS apps I see doing this currently: Carvana Cash App IMDB Kick Turo Twitch Instagram Prime Video I’ll stop now as it’s nearly every app. Even Apple’s own apps do this— directly from the company who controls the UI of the app store and the developer experience of filling out the form with placeholder messages
It depends. For stuff like npm packages, where the downstream consumers have to make a conscious decision about whether to adopt the update or not, I absolutely think it's worth getting it right, especially for major version bumps. I myself am the user of an open source code gen tool that does not have comprehensive changelogs, and it makes me want to tear my hair out because we can never be confident when upgrading whether or not we're going to end up with changes that will break our workflows or our customers' workflows.
But for consumer apps, honestly, maybe not? Even at companies that do good consumer changelogs, they're generally considered marketing content. Other posters in this thread made the points that most people updating consumer apps are not even going to see the changelog message, and that app stores have effectively punished companies for providing detailed changelogs by holding app store releases over them.
And given that for larger companies so many of them are actually controlling their feature releases on the backend and not on the client side (you might add the capability for a feature on the client months before you actually set the rollout to 100%), trying to convey those updates in the client-side changelog can be hard to do in a way that consumers will understand and can often generate a lot of confusion and support tickets. After all, we don't expect a changelog entry every time a website updates, and I feel like every day mobile and desktop apps are getting closer and closer to that category.
Well yeah, it's obvious that companies love the "anything goes, no expectations" update model of websites and want to apply it to apps as well. I just don't think this is in the interest of users.
As an exteme example, we've had the situation several times now that a useful app that was maintained by a single person was eventually sold to some adware or malware company - who quickly pushed an update to stuff the app full of ads or do worse with it.
This only works because of the "ask no questions and accept the auto update" standard the industry established.
In the interest of openness and honesty to the user, that would be more reason to document those preparations in the changelog, so users know what to expect later on, if more features are activated.
I totally disagree, with today LLM with large context generating CHANGELOG.md based on latest modification and git release tag is quite easy.
I second this. It’s now supremely easy to have a session hook which writes an atomic CHANGELOG along with ADRs for consequential decisions.
Who needs changelogs if you can have animated mystery buttons and "look at our new feature!" overlays instead that pop up at the worst possible time and cannot be read again once closed?
I have stopped trusting automatic software and operating system updates, they take away useful features or break functional user flows or introduce unwanted AI slop too often. So I am very much back in the boat of software needing to justify an update for me to install it.
Just the usual symptoms of a profession which was never regulated properly, compared to an engineering profession. So anyone could drag it around however they please. Look this shiny thing I made, this is much better than the competing not so shiny things we use daily. You are a peasant not using the most shiny thing on planet earth, this is the new epoch.
Do we need this? Nah. Do we need this horrible abstraction over a zero complexity thing? Suuuure.
And this will lead to horrible issues later on. This is just another symptom.