The problem is often the "bugfixes and performance improvements" are a list of 60 things, and for almost all users "there are less crashes and it is faster" is all they would want to know. How many users want to read (OK, possibly people here)
"On some versions of glibc, the 32-bit specialisation of memcpy which used SSE2 instructions had a bug when the memory being copied crossed the 2GB boundary, so in that case we now use our own memcpy"
Or "Changed some internal lists to be only be sorted when they need to be rather than eagerly sorted whenever elements are added, which speeds up start-up time".
I think the key is describing the user-facing effects and impact. This means knowing your users (are they developers, IT or highly technical? Do they automatically or manually update quickly, or do they take time to evaluate before rolling out updates?). It's a way to convey continuing value to users and convince them it's worthwhile to keep paying, and get motivated to get the update.
I'd try to change what you wrote to something like:
"Fixed out-of-memory errors on some 32-bit systems"
"Improved startup time for configurations with lots of items"
This makes it easy to gauge if this update is important to get installed ASAP, such as fixing something they've experienced or are likely to experience.
Grouping "several UI fixes" or "performance improvements" is usually fine, but I tend to call out something like "fixed UI bug where a network error could result in changes not being saved with no warning" or an issue that a sizable chunk of users had reported.
Doing this well takes time, though, as you have to synthesize the internal ticket summaries, PRs and/or commit messages and reword almost everything. This is understandable for open source or free/indie apps, but for subscription/"enterprise" software it's definitely one of the differences between "great" and merely acceptable (or worse).
> but for subscription/"enterprise" software it's definitely one of the differences between "great" and merely acceptable (or worse).
I couldn’t agree more.
I tried writing more informative but easy to digest release notes when a couple noisy users mentioned at a trade show that they wanted to know more about our bug-fixing efforts.
To my surprise, we got a huge volume of communications from our users that they loved our new release note style and to keep it up.
It takes us about 1 hour / release to write. We release small changes weekly and large changes monthly to about 1mm MAUs.
> I'd try to change what you wrote to something like:
I'm used to seeing from well managed projects a paragraph saying that there's new feature A and bugfixes and performance improvements.
And then a detailed change log with big feature A, smaller features B & C, and 10 bug fixes described. Maybe 2-3 performance improvements that are expected to only -really- help with degenerate cases.
And then, there's a dozen things that aren't considered important enough to be in this list.
For closed source systems detailed changelog is very nice. "Fixed USB reset issues" is close to useless, when you try the new firmware and it still exhibits USB reset issues. More detail the better. And describing the actual changes ("increased XYZ timeout on USB resume") instead of symptoms they tried to address ("we fixed the USB reset" - not) is actually much better.
I think focusing on "user facing impact" is a good idea and something I'll be using in the future. One challenge is that developers don't always know the user facing impact of their improvements.
For example if I notice a logic error in a system and fix it, I may not know what if any software configuration could trigger the error. If it were obvious, QA would've found it. And given the choice between further investigation or leaving the bug unfixed, my employer would prefer the latter.
Or one time I was working on a new feature that required speeding up the system's implementation of malloc(). That improves the performance of the entire system to varying degrees. Pinpointing exactly where the user's experience improves would require extensive benchmarking outside the scope of the work.
For us, not that much time, as everything goes through the bug tracker (even enhancements) so it's mostly a copy-pasta job. When I submit a fix for a bug, I'll often edit the subject to accurately reflect what the problem actually turned out to be.
There’s also a mitigating liability aspect to this. If you start providing minutiae detail, you may start revealing pretty big faults that have escaped to prod. People question the safety of your product and now you’re open to lawsuit or at least micromanaged by some unforgiving end-customers. To cope, you start to not fix certain problems so you won’t have to report the bugs or you start lying what the bugs were. I’m not so sure it’s on net a useful direction to be quite that open.
Back in the 80s when I was starting out in the compiler business, I thought it would be a good service to include with it a list of the known bugs.
It didn't take long before a magazine reviewer did a compiler roundup and simply printed the bug list as his "review". It was a disaster for my business.
It took me 20 years to get over being brutalized by that and make the bug list publicly available again.
I had a competitor do something like this to me in the 10s.
We had a structured weekly/monthly small/big release cadence compared to their bi-annual update. When we started thoroughly documenting our bug-fixes publicly, they used that against us in negotiations on a large deal. Basically alluding that our software was buggy, seeing that we had something to fix every week. Luckily we thwarted that logical fallacy by asking how many bug fixes they did last year and had no real answer.
People suck. Glad to hear you’ve overcome the fear on this, it’s worth it and I also still maintain a public list of bug fixes.
This is likely why useful and important details in changelogs are suppressed. Products where owners/managers value and emphasise transparency are much better at this, but it requires a specific culture. I mean - it does take guts to say "All media in the application could be downloaded without authentication by anybody on the internet. This has now been fixed."
The take-away from this is if a vendor doesn't provide a good changelog, it's fair to assume they're trying to cover up incompetence (or some other shortcoming).
With good automated testing, a bug recurring should be extremely rare. A piece of the software that constantly has bugs is a sign there's high technical debt that needs to be addressed. New features consistently not working could be a sign of a problem in the team/org itself (not the right people, enough people, or enough time allocated).
Even with all the best practices, big faults will make it through sometimes -- that's just the nature of most software dev. I think the best way to handle them is be transparent, but also be specific. "Fix bug where entire database can be corrupted" will cause you a lot of grief (rightfully so). Something like "Fix critical data corruption bug when saving a record containing specific trailing unicode characters on systems with libzip 1.3.3 or earlier installed" is much better and helps reinforce that:
1. You have thoroughly investigated the problem
2. The scope of problem is limited, and doesn't affect all customers (even though it could be most)
3. It's understandable how such a bad bug could happen and why testing didn't catch it
If you fuck up, admit to it, fix it and learn from it.
If you fuck up bad enough that someone had a good case against you then you should make them whole and use the opportunity as a wake-up call to make sure this never happens.
I think the author of the article brings up a good point regarding this, though. If you're a non-technical user, you're not going to read it at all. You might update, you might not, but you're not going to look through the list of changes.
If you're a technical user, you know it's unlikely that update == "more crashes and slower load times" so saying the opposite isn't helpful, and a list of things might be helpful.
So as a user of an app you probably fall into one of 3(ish) categories:
1. You read the changelog and something is relevant to you.
2. You read the changelog and nothing is relevant to you.
3. You don't know what the changelog is.
Listing the bugs that are fixed helps some of these groups. "Bugfixes and performance improvements" is a given, and helps no one.
Even when I'm in group 2 and don't want to read every update, I'm reassured by the fact that users in group 1 can find relevant information. I also sometimes move from group 2 to group 1 when I need to track down what version introduced something that's just now causing me problems. :)
I tend to fall in either 1 or 2 depending on whether I've been bitten by a specific bug and need to know if it has been fixed.
The worst changelogs are the ones that say "Performance improvements and bugfixes" only to find out the entire user interface has changed after updating.
Some non-technical users do read change logs, looking for new features. Even if they take every update, the notification of an update pings the hope that there may be something useful or fun. "Bug fixes and performance improvements" means "you need this update but there's nothing you really care about".
So there are least two kinds of updates, those with user-facing features and those without. Currently both come in the same stream. We could come up with a better way of differentiating the two, including not notifying users at all when the boilerplate "fixes and performance improvements" comes on. Just update the app and what the user doesn't know (hopefully) won't hurt 'em.
> If you're a technical user, you know it's unlikely that update == "more crashes and slower load times" so saying the opposite isn't helpful, and a list of things might be helpful.
It's precisely because an update might bring more crashes that I'd like to see what changed.
> If you're a technical user, you know it's unlikely that update == "more crashes and slower load times" so saying the opposite isn't helpful, and a list of things might be helpful.
Umm, no; if you're a technical user, you know it is likely that update == "more crashes, slower load times and useful features breaking or disappearing entirely", regardless of what the changelog says, because you've observed exactly that happening with eg your webbrowser or image editor.
> "Bugfixes and performance improvements" [(]is a given[)], and [(]helps no one[)].
See Reaper (the audio thing) for the opposite extreme. The changelog lists everything, so sometimes you miss significant new features because they don't make a big deal about it.
They put a whole notation editor in and didn't say anything past the item in the changelog. Most tools like it have a notation editor, but it's a $300 addon instead of a free update to the standard $60 package.
Doesn't have to be coverage of every minute detail down to the implementation, but a rough outline of at least the most significant changes seems like a good middle ground. On several occasions I've revisited a feature (or even an entire application) upon seeing that an issue I've had has been addressed in the changelog.
A lot of people here would like this level of detail, actually. But general apps are intended for the general population, which is why big orgs go for the minimum watered down version. It's more work and overhead if they confuse their users.
It's important to list what bugs you fixed. You can do fancy things like group your changelogs under headings if you want to make it easier to maintain focus for different audiences. A CAD tool I use, for example, lists every single bug fixed and references a ticket number with each. This is extreme, but much better than the opposite extreme.
It lets me know when I can stop using workarounds, or alert me to landmines I've unknowingly tripped and lets me go back to verify old designs.
Regardless of who the user is, a changelog is supposed to tell you what actually changed. If you're not going to do that, don't bother having one. But if you don't bother writing one, I'm not going to bother updating to the new version. From my (the user's) perspective there's no incentive to do so unless I know what I'm getting. There could be anything in there, so I'll stick to the devil I know.
I prefer the detail. You could always make the first line: “bug fixes and performance improvements” with details following. Then people who don’t care can ignore the details, but people who do care can get an understanding of what the change is about.
Deep understanding of a change is really helpful when looking through history or trying to make sense of why this particular line was changed, etc.
The reason these bigger apps just put "Bugfixes" and "Performance Improvements" in their changelog is because when you have many teams contributing to the software not only through actual code editing but also feature flagging what features go out on what release, rollback policies etc this becomes a nightmare to fill in. Doubly so when different users are receiving different experiences.
The article says at the end: "You see? Not that hard right?". It is that hard in bigger organisations.
Apple has a much more traditional engineering structure and traditional release cadence though. A lot of the "worst offenders" of these types of release notes are structured and work much differently. They release updates 1-2 times a week, sometimes release features weeks after the code has shipped to users, and sometimes in stretched out rollouts.
They say there if there is a will, there is a way, so in a sense I agree that these companies probably could do something about it if they really wanted to, but I also don't think it would be easy, and considering how few people actually look at release notes, I am not sure the investment is worth it.
> when you have many teams contributing to the software not only through actual code editing but also feature flagging what features go out on what release, rollback policies etc this becomes a nightmare to fill in.
This is a terrifying sentence to me, because what it implies but doesn't say outright, is that there's not a single person in the organization who actually fully knows what is being released. If there were, then they should already have this information!
Honestly, if you don't have a release manager with a 30,000 foot view of the operation, you probably have bigger organizational problems than "it's hard to know what to fill in on the app store's release notes".
This is how retrospectives on supply chain attacks start, basically.
> This is a terrifying sentence to me, because what it implies but doesn't say outright, is that there's not a single person in the organization who actually fully knows what is being released. If there were, then they should already have this information!
It’s not the collection of the information that’s difficult, it’s delivering it to the user in an appropriate way when you use phased rollouts with feature flags.
The change log that the App Store presents to the user is static and identical for everybody. The changes that a user actually experiences are not. So you might have 0% of your users experiencing a certain feature when the release goes out, 10% a day later, 50% a day after that, and 100% at the end of the week. Or, if the metrics show a bad response, it might end up at maximum 10% seeing it, and then it dropping back down to 0% the next day.
Apple gives you a static text field to enter the change log information, with limited length. If you have ten different features to release, your users will all receive them at different times, and not all of them are guaranteed to make it out to everybody, how is a static text field supposed to deliver that information?
"Begin rollout of feature <foo>"
"We are rolling out <foo> in <timeframe> to ensure <x> about <y>, and rollback if <z>. You will notice you have <foo> when <bar>."
If you don't put anything about new features, don't be surprised when users don't use them (because why would they know) or complain what something "breaks" (or just changes on their workflow) because your changelog communicates nothing.
> "Begin rollout of feature <foo>" "We are rolling out <foo> in <timeframe> to ensure <x> about <y>, and rollback if <z>. You will notice you have <foo> when <bar>."
That’s a guaranteed way to get users complaining that they don’t have a new feature that you “promised” that they may never receive. It also isn’t appropriate for multivariate testing and just isn’t going to be understood by most users anyway.
There are way to do this in a decent way, but you have to do it within the application using your own logic. The change log provided by the platform is inadequate.
> If you don't put anything about new features, don't be surprised when users don't use them (because why would they know)
If you need to tell your users about new features in the App Store change log, then you’ve already failed because almost nobody sees it. Users know about new features because either a) it’s obvious when you use the application, or b) you tell them about the new features somewhere they will actually see it, at an appropriate time.
> or complain what something "breaks" (or just changes on their workflow) because your changelog communicates nothing.
A change log does not prevent this. You are attributing a lot of power to the platform change log that it simply does not have.
Many applications are big enough that no single person can hold the full details of what’s being released in their head. If a release contains a hundred changes from a dozen teams, there’s no way a VP or CTO sitting on top can understand them all in any depth, so “performance improvements + bug fixes” may well be the full contents of the 30,000 foot view.
That doesn’t mean it’s impossible to produce more detailed notes for a big application, but it’s a pretty involved process basically requiring a “release note manager”, not something that happens by default.
> there's not a single person in the organization who actually fully knows what is being released.
Sometimes there is, but as siblings point out, it's difficult or not cost effective to distill this information into an app store changelog blurb.
More often (in my opinion), it's the terrifying situation you describe. Nobody know what the heck is going on at an overall level. Which can work surprisingly well, but often means efficiency (network, memory, cpu, disk space) is very hard to come by.
No. what it signals is that app releases are decoupled from feature releases. Of course people know when a new and important feature is being released, it's just completely independent of when the app store update goes out.
If you're shipping a mobile app with client side code (so, nearly all of them), there is no good rollout process.
You can't ship a quick update with Apple, because review isn't quick. Users who upgraded soon after release will be stuck with something broken until the new version is available.
You can usually ship quickly with Google, but users are slow to upgrade, but may have caught your first one, and not get your second one for some time.
As with many others here no doubt, I spent a lot of time in 2020 viewing diffs between library versions, reading changelogs, and tracking upstream bugs/features.
Although I'll try to resist going on too much of a pro-FOSS rant, the change audit process is much easier for open source projects since you can read not just the changelog entries, but also the corresponding code to verify the claims.
That helps with various things including developer trust - it helps you determine whether a project and authors use test coverage to reproduce bugs and prove their fixes, whether performance improvements are measurable, whether there are risky side-effects to look out for, and so on.
Increasingly I think that these kinds of 'software due diligence' should become part of recommended software engineering workflows, and that makes me wonder whether some of the repetitive aspects can be automated.
A genuinely user-focused, trustworthy app ecosystem would, I think, allow some of these 'change audit' processes to be visible to users so that they can make informed upgrade decisions, and to create a marketplace incentive for upgrades to be reliable.
This is precisely why I started https://keepachangelog.com/ many years ago. Release convenience shouldn't come at the cost of properly communicating about notable changes for software users (whether developers themselves, or software consumers).
Instinctively, developers reach for automation to solve this problem but this is an editorial problem for most software. Code changes very rarely map to notable changes for your intended audience. Even with rigid system like conventional commits, you can't entirely automate proper human-focused changelogs and release notes.
You're going to have to clean things up and editorialize if you really care for your software users to understand what notable changes are included in a given version release.
If you can't think of any, maybe you're releasing too often. If it's impossible to tell things apart because there are so many changes as another commenter pointed out, I think you have a way bigger problem.
With many apps an issue for changelog writers is that often behavior is tied to feature flags, which can be remotely enabled. Thus a new feature is rolled out in the app but only visible to some testers. Only after a while it's enabled for all users. Thus app release is independent from availability of a feature.
That said "Bugfixes and performance improvements" is as useless as it gets ...
It depends on the feature. For things that involve material changes to your app or a feature that you don't want Apple to be surprised about, usually you will include user credentials in your submission that have that feature enabled and give them a heads up. If's a smallish feature, you don't usually sweat app review. It's obviously not a perfect system.
I'm pretty sure that's what Fortnite did right before they got kicked out of the App Store.
Before my company implemented IAP in a few of our apps we did the same thing, but decided the risk was too great. Getting rejected is one thing, but getting your account terminated is obviously a much bigger deal.
One of the reasons larger apps post unhelpful changelogs like these is because they probably run a feature flag/experimentation system. It is a backend driven system that allows app developers to remotely switch on and off features and code changes. This is really useful when rolling out updated features, you can roll it out gradually, eg 1%, 5%, 10%, 100%. Roll out a new feature 1% and notice its crashing for a subset of those users? Roll back the flag so users see the old UI and fix the problem for next release. It’s better than updating a feature for all and having it crash for everyone (yes, even with testing sometimes bugs sneak through, especially when you have millions of users).
It also allows app developers to bucket users in groups and A/B test experiments on users to see what works best. It would not be uncommon for the larger players (Microsoft, Google, Facebook, Pinterest, Uber, Spotify, etc) to have 100s or 1000s of experiments running concurrently. It also decouples rolling out features from App Store releases.
Having said that, I also hate generic changelog messages and not defending the practice.
If new features are to be launched with the build, write it in the changelog and add "(rolling out)" or
"(coming soon)" next to it.
I also have automatic updates off and I really like checking changelogs to know what new things I can play with.
And I don't mind reading 'bugfixes and performance improvements' ... but only if that's really what the new version is about. I like changelogs, but even for me a 'we fixed an issue where if you enter a 1025 characters text into the title textbox and press back twice while rotating the phone the app closes' is probably too much, but if you added a new option to increase the text size please say it, I don't want to check all the settings screens each time each app updates, and more often than not someone tells you 'hey, aren't you using this option?' No, no I wasn't, because no one told me.
Are you a big company and you have automated updates? Why not have an automated checklist of changes too? I'm sure you have a 'roadmap list', so use it.
I used to love posting detail about what I change in my apps. But now the text isn't really surfaced - folk have automatic updates turned on, and the text is deep in the app store now.
My changes are mostly technical when I use the "bug fixes and performance improvements" text, but I tend to write more for the app store reviewers to let them know what is going on. I know they read it.
In the end my audience of users are very non technical. I am authentic to them, that is the image that I sell my apps with, and I am good at it. So they just don't care that I've updated library X, or improved error handling somewhere, or I support Apples latest devices now. They do have faith that I am doing the right thing, and they write to me as if they know me, and I like that.
I'm very passionate about this idea for open source software, especially things like ruby gems or npm packages that I might use as a dependency, but for some reason I can't muster the indignation to care about this for apps. Maybe it's because I care primarily that the app works and the latest version is stable. I'm generally not going in and considering upgrades to apps strategically, and even if I did I have no ability to see the previous changelogs let alone install those versions. If for some reason I want to avoid an upgrade now I'm living on borrowed time and need to start thinking about a replacement or carefully curate my backups so as not to lose access. Sure in a perfect world it would be nice to have perfect changelogs, but it's so far down the list of things I want out my apps that I place zero value on it.
I just looked at WhatsApp (one of his examples) and it has a detailed "what's new" in both the Apple and Android app stores that's listing three high level features.
Sounds like the screen shot he took in September really was a bugfixes and performance release.
So it sounds like these apps (at least, WhatsApp) follow a wise policy - tell the users what has changed that matters and don't drown them in irrelevant information.
I had the same policy for my teams - tell users 4-5 new features/changes to workflow they are going to see and for g-d's sakes, do not drown that out by listing 400 irrelevant infrastructural changes we happen to be pushing out.
Thank you for choosing [app] - the best [thing] for [thing that it does]! We are committed to continuously improving the experience of bringing you the best of [thing that app does]. We update the app regularly so we can make it better for you. Get the latest version for all available [app] features. Love [app]? Rate us 5 stars!
Meanwhile nothing at all changes with updates but there are hundreds of server-side settings that change all the time because metrics gotta grow. Eternally. Into infinity. And don't you dare get used to the UI.
One time I wrote simply “bug fixes” for an app update and it got rejected because the description was too short. I changed it to something more in the lines of “bug fixes and improvements” and it got accepted. I generally like writing changelogs for users but I also wonder how many people have automatic updates on and never read them.
> If that is all you're going to put there, then just leave it blank.
Well, I would love to. Unfortunately neither Play Store nor App Store allow you to do that... so "bug fixes and performance improvements" it is, 99% of the time.
These are changelogs for end users, not fellow developers. In fact I expect that even these "one line notices" will be dispensed with in future as the concept that any software or device requires an always-on connection to the Internet becomes fully normalised. Apps/devices will simply update and that's that. You won't be given any sort of option or toggle. Does anyone seriously ask the govt NOT to maintain a road or bridge? Such will be the case with software too.
Individual freedoms and privacy have no future in the direction technology and society are going.
Worst offenders aren't even those. Some go as far as an 'Information not provided by developer', and the worst of them all - Netflix's 'You just worry about what to watch next.'. Irritates me to no end, I now only update manually and if there's no apparent benefit I just don't. Saved me from seeing some apps' changing icons into something awful, or hostile UX redesigns. It was a shame when Discord, who used to have some of the very best changelogs, turned into this practice.
One reason might be that they are not automatically generated. I hand-edit each entry.
Sometimes, I copy and paste the changelog entry into the last commit of the release (but I make sure to have a short, succinct initial sentence, as that is what shows up in Git browser history).
The changelog may end up being a lot more "generalized" than the commit comments, though, as it's meant to be read by users.
I appreciate the kinds of changelogs that you usually get with developer tools, where they are like encyclopedias.
I automate the app deployments for our team and “bugfixes and performance improvements” is the changelog because it’s totally automated on release. Yes the automation could grab something from the commit logs but I’m not confident I’d want to expose some of our commit messages. Also recent versions of iOS have further hidden away the update ui making it very hard to find for most users, so why bother taking the time to add them manually when 99% of your user base will never see them?
I think I'd argue it's not "totally automated" unless skipping the changelog generation step was the intention. In which case no need to justify that with any reasons, that's your (valid) choice to omit some documentation. We used to maintain our "customer-facing" changelog as we merged the associated code but that did create work when trying to release and finding some people had forgotten to provide an entry, which ultimately reduced release frequency. So now we don't include a changelog in the release itself, we create it after the fact and it's more of a "living" document hosted online (having to create another new release just because of dumb mistake in your latest changelog is really annoying). For those that are really interested, they can check the commit logs. For those less interested, they can wait for the online changelog to be written. It's likely they'll only have to wait a few minutes. Obviously the former is easy for open-source projects. I'm not convinced our new way is better yet but I'm willing to wait and see if the release frequency improves.
This topic and responses to it warms my heart. :) I've made it a habit for my current project to turn changelogs into blog-like material for the end-user. The kind of changelog I would like to see from other software, especially the kind I care about.
If an app is good enough, developers and managers and "agile coaches" and such don't stop, they start doing busywork. It looks like they're working and progressing, but all they do is scare users away with by removing features, breaking workflows and more horrible stuff. You're just making money for the shareholders, nothing more. They don't care about users...
In the case of many popular apps, it's a bit more than that: they're actively fighting what they perceive as bad actors, that is people trying to use their app not as intended, using their protocol outside of the official app and so on. In this case they have nothing to gain by describing the changes in more detail in the changelog.
The D compiler have had a great changelog since years and it has made a difference to popularize what went into an update. Each major change comes with examples, and it's great content.
Yeah, it is nice to know what the actual changes are, rather than a vague 'fixes were made' statement. Nintendo's update logs for games have to be some of the most hilariously vague in that regard, with many of the updates being just:
> Several issues have been fixed to improve gameplay experience.
But at the same time I guess I can see why companies and project creators don't go into more detail. Maybe the actual bugs fixed were so weirdly technical that most users wouldn't understand them at all, or care (if the user hovers over this button for 1/300th for a second, there's a 0.0001% chance their next message might not save properly). Maybe they (perhaps sadly) don't remember what exact things they fixed, since they fixed so many bugs.
Either way some more detail would be nice for those that do care about this stuff.
when we build a new feature, it's gated by a flag controlled by the server. The app version with the feature is distributed well in advance of the intended rollout. So, we can't even put the new feature in the change log for the update that includes the feature, and the rollout won't be associated with an app update.
All we can really put in the change log is bug fixes, and the circumstances that result in a bug can often be obscure and hard to describe in user-facing terms, so it gets summarized: "bug fixes and performance improvements". And for the play store and the app store, we have to put _something_.
The worst of these is the "Google" app. For over a year, every single new version has the exact same four-entry changelog, which translating from Portuguese is something like: "enhanced search page appearance; new doodles designed for app experience; off-line voice actions, available only in the USA; web pages opened directly within the app". I have the slight suspicion that most of the almost weekly updates to the "Google" app do not have these four changes... for that app, "bugfixes and performance improvements" would actually be a better (more correct) changelog.
The FOSS community still campaigns the idea of Open Sourced software on desktops. Why then is the same not as popular in other platforms like iOS or PWAs? I truly wish I could visit github.com/[my-iOS-ap]/project and contribute or read the geeks' changelog while the app store can have the simplified changelog for non-coders. This is one of the reasons I think https://blink.sh/ is one of the best iOS apps out there.
The big issue is probably that the mobile platforms have significantly different monetization models and incentives. It’s possible to run an open source app, but you’re doing it mostly out of the good of your heart a lot of the time.
That's just a consequence of the dreaded "move fast and break things" culture. Ideally, you should only be updating your app to add new features or to address issues that have arisen with an OS update or new hardware for example. And you should only be releasing new features when they're ready, not when current time matches a certain value. But for some reason you can't be doing any of that if there's money involved.
In an "app store" context, the apps don't serve you; you just generate content/engagement for them. The apps you're looking at don't WANT you to be informed because you might choose not to use them. These notes are just a formality standing in for forced automatic updates. Spotify on Google Play is particularly insulting. They basically tell/shame you that you should just always update without caring about the changes.
>In an "app store" context, the apps don't serve you; you just generate content/engagement for them.
This is a non-sequitur.
There are all kinds of apps in an "app store" context, and the apps I use serve me very well, thank you. I also don't generate any "content/engagement" for any of them.
Whether apps have good changelogs or not is also not a factor of whether the apps are in an app store or not.
You maybe meant to say "social apps" as opposed to "app store" apps.
I guess I'm focusing on the ones at the top of the food chain, and the what I think is the predominant relationship in app stores, not necessarily the social ones. Eg the Microsoft ones in the article
When I make performance changes I like testing the actual gains on the live server and add them to the changelog, something like: "Improved profile page loading speed by 25%".
For early-stage startups, writing changelogs is also a great way to close the feedback loop with their user-base. We write detailed release notes at Raycast [1] to highlight feedback that we addressed. This way our users see that we care about their feedback and feature requests.
How much value does the average user get out of better patch notes? None, since they don’t even read the patch notes. So is that worth the time for each issue to write and edit a user-facing piece of documentation?
Every little task like this is a waste of time and mental energy that slows down useful work. In my opinion, this is just not worth the effort.
I too basically disagree with the author (for reasons I'll go into below), but I think it's worth unpacking a little further that high quality release notes can form an important part of your communication strategy with your users. Note: high quality.
Many years ago I worked for a tools company where, for our less popular tools, user count would be in the thousands to tens of thousands, and for the more popular tools, it would be in the hundreds of thousands. Every single time we put out a release you could guarantee that a handful of people would ask for release notes even though we'd always publish them. Clearly people wanted them.
Now I work for a company where our platform caters to two very distinct groups of users - one group internal, the other external. Particularly for the internal users release notes are hugely important in order to avoid disrupting their work and deliverables to customers.
In both companies we've often had an "additional bug-fixes and performance improvements" item in the list.
Why?
Because people only have so much attention to go around: they're busy and, particularly in my current role and with our internal users, it's critical that we draw that limited supply of attention toward the most important changes. That's much more valuable than sending out an exhaustive document of every single change every time we do a release. We've found that if we supply exhaustive notes, fewer people tend to read them, and we get complaints that they're too long. As you've already suggested it comes down to ensuring that the release notes you provide are actually valuable to users.
Together with other documentation and training materials, release notes can provide a useful jumping off point for learning how to work with changes and improvements to our software.
(Not everybody reads them, of course, but having them does at least mean that when they inevitably ask for help/information, we can point them at the release notes as a starting point.)
Maybe like a couple bullet points, nothing too technical, but it’s a good spot to talk to your customers and make them happy.
It does depend on the product though. I can see a developer tool maybe even just going so far as to putting out their internal change log, but for other customer segments, it’s best to keep it short and (hopefully) funny
Most general users of apps on phones wouldn't give an absolute crap if you "fixed a buffer overrun in the X function", because that means nothing to them. If they read that you've made performance improvements, then great they can continue to play Candy Crush but not have it crash so often. They won't CARE that you "optimised the use of the strcopy function" or some crap like that.
Remember the app stores are targeted towards consumer users of phones, not tech people that live on Hacker News websites.
As a startup we write fairly detailed changelogs weekly [1]. For us it has been a major way to communicate all the new features and fixes as they come available to users. It’s also a good way for the team to celebrate their accomplishments. I was surprised to learn it also had helped with investors and generally marketing.
Usually the person who was a major contributor to the highlighted feature of the week writes the changelog and then we look through our PRs to add anything that could be interesting. We don’t include things like “migrated x” “upgraded library x” if there is no visible benefit for there.
"On some versions of glibc, the 32-bit specialisation of memcpy which used SSE2 instructions had a bug when the memory being copied crossed the 2GB boundary, so in that case we now use our own memcpy"
Or "Changed some internal lists to be only be sorted when they need to be rather than eagerly sorted whenever elements are added, which speeds up start-up time".