For example if you visit the App Store now, you’ll see the many app developers, especially the big ones such as Twitter, Facebook etc., are using the same changelog entry for every, single, update: “Thanks for using X! To make our app better for you, we bring updates to the App Store regularly.” The problem is, this doesn’t tell me anything about what to expect. No, I see that I shouldn’t have anything to worry about because the new features are throughly UX-tested, and as an app end user there is not much to consider anyway (it’s not a framework I’m using in production, right?).
The problem is, the changelog matters when Facebook removes messaging functionality to push its users to their new app for some for-profit reason. Changelog matters when your favourite app which has been free for the past couple years have decided that it’s monetisable now and there are intermittent ads in your feed. It matters when they think you don’t need a functionality anymore and proceed to remove it, but you actually do.
I think changelog should be enforced far, far more strictly for closed-source software, and especially for those on App Store and Play Store.
Although, meanwhile, large companies like Apple and Google have started including surprisingly high-level and compelling release notes or changelogs to end-users in things like Chrome and Keynote.
Smaller shops like Transit, Halide, Darkroom, and many others are going the opposite direction of Twitter and Facebook by offering very detailed and compelling (although sometimes a little too over the top) changelogs for their major releases.
One thing I wish people did more, and I feel like I should carve out a section about this on Keep a Changelog: explain exactly what bugs were fixed. I know discrete updaters are becoming more rare with auto-updates, but seeing a specific bug that affected you specifically squashed in a release is perhaps one of the greatest values of changelogs, especially in the case of open source software but also with closed source apps.
I wish. It's rampant on Android, too; of my recently updated apps right now, about half of them have release notes on the order of "bug fixes and performance enhancements". Even Google does it on their big-name apps!
It shows maintainers which are the real issues affecting people, allows two-way communication about the bug, and keeps the changelog clean.
Nodejs is an example of a project that seems to mention every single fixed bug in their changelog, making them so long that I'll probably miss the things that really matter while skimming over them - especially when jumping ahead a few versions.
I disagree. Sure, it's a signal, but it's quite distorted.
Suppose you have an issue that affects a lot of people, but has a simple workaround. You may not see this issue since no one bothers to file a bug. If in doubt, I'd prefer to fix a papercut that affects 50% of my users vs. a catastrophic show-stopper bug that affects 0.01% of them.
> Apps now must clearly describe new features and changes in the “What’s New” section of the App Store. Several of the large social network companies have been using a practice where they reuse a generic update text for every release and then enable new features remotely on a per-user basis. This appears to no longer be permitted.
that should still be permitted, no?
they'll just have to write "we added feature x, which we'll slowly roll out to all eligible users."
This would be vastly preferably to the current: "Bug fixes and performance improvements"...
"Every update of our Facebook app
includes improvements for speed
I would like to check before I upgrade, if an app removes a feature, regardless of whether I'm using the feature or not.
That doesn't mean they have to hide the existence of those features, or the reason for the update.
That's a pretty uncharitable interpretation. After all, you used your favorite app for free for a couple years. Maybe they ran out of money. Maybe they tried to monetize in another way, but it didn't work and ads were the fallback to keep the service afloat (though also possible ads were the plan all along once scale was achieved). In any case, your favorite app isn't free to develop or host and you're not under any obligation to use it.
Flash degrades on writes. There's not that much space on a phone so why spend writes on weekly updates with no visible benefit.
App makers thought that monolithic multipurpose apps didn’t work well.
Google did the same thing.
I personally find it annoying that Messenger is integrated into Facebook enough that I’m notified when there are pending messages, but not enough that I can’t check my messages on FB app...
Version 1.0 was released introducing: a much cleaner website presenting the guidelines in a more digestible way; 13 new translations; a semi-decent versioning system to help synchronize translations; and a lot of clarifications and updates based on feedback and conversations that occur regularly within the project issues: https://github.com/olivierlacan/keep-a-changelog/issues.
I know trying to get ahead of the torrent of critical comments is pointless but let me summarize: yes, I know you think changelogs have been defined before. But you know just as much as I do that most changelogs (or whatever you decide to call them in protest) are terrible and not as helpful to software end-users as they should be.
There's been a lot of progress in the past 3 years alone in that regard. It's nearly unthinkable for an open source project to not include a decent changelog for each release. That's good. There are still a lot of smaller, less known, or older projects that could be improved with some basic changelog hygiene. If you're interesting in helping, please do, and if keepchangelog.com can help I'll be glad.
The usual "Make sure to grab the latest update to get the greatest experience. We bring you performance improvements and bug fixes every 14 days" or some annoying joke about dusting code off, taking the trash out and fixing the space-time continuum is getting pretty tired.
- Fixed flickering lower-right pixel when hovering over close button with a stylus on devices with more than 300 % UI scaling applied.
- Fixed alignment issue in About dialog.
- Improved help text for Gizmo frobbing feature.
To me a changelog should prominently document changes in function and behaviour. I don't particularly care if an exception message got a typo fixed, but I do care about a new feature, if a login problem for a subset of users has been resolved or a crash under weird circumstances has been fixed.
I must be a crazy user, because I generally like reading through changelogs to see if an update is worth applying because it addresses a specific issue I am having, implements a new interesting feature I want to try, or fixes critical flaws.
Luckily, though, public bug trackers are generally a good way to find out at least the 'is my bug fixed' part without the changelog (your issue is closed as 'fixed in X.Y')
I write the changelog for a product. In fact I write two changelogs - one for engineers and one for customers.
- [New Feature] Added ability to ___
- Improved logging on ___
- Fixed a memory leak on ___
Not every change can be explained in one sentence to users. Internal logging? Memory leaks? You're speaking a foreign language. Those entries must be thrown out when making the changelog for users.
Eventually, there comes a release when you have thrown everything out. What do you write? "Bug fixes & enhancements".
So we create our change log (they are part of our 'release notes' actually) with only the user in mind but we reference the bug tracker number next to it.
This is what we check in to the 'source' for the release notes.
Then when we post to the 'outside world' we just remove those tracker numbers (takes a few seconds).
That way the engineer can see the 'easy to understand conceptually' bug fix/enhancement and if they want to know more then they can see the Tracker reference and go and look up the 'real meat - with all the discussion and threads etc.
For those bug fixes that we 'don't' document we have our source code software.
We maintain a CURRENT_CHANGES.md with those sections. When we do a release, we move the contents of CURRENT_CHANGES to a new entry in RELEASE_NOTES.md.
One of these days, I will get around to writing something that displays RELEASE_NOTES in the app, without the Internal section
https://news.ycombinator.com/item?id=12370119 (45 comments, 3 years ago)
https://news.ycombinator.com/item?id=9054627 (43 comments, 4 years ago)
See also issues/pull requests in the repo:
Ideally, one would have something that can be connected to project-management tools rather than github, e.g. Trello: when you mark a checklist or archive a card, the title should go in changelog.
I started doing this after reading "The Pragmatic Programmer" where it's argued that the DRY principle should apply to everything including documentation.
It starts with the bug tracker. So when entering something in that I'll also add the text that I want to appear in the changelog for the user to see (these lines will have a // at the start).
When a bug/feature is completed a commit is made and the text in the bug tracker is the commit comment.
If the commit comment has a line starting with a // then that line will have another line inserted above it //Bug fix: or // Feature:
Finally on building the distributable the changelog is constructed entirely from the lines in the commit messages that start with //
- compiles all commit messages since previous version
- filters unwanted messages (according to special tags)
- groups them by category (fixes, enhancements, ...)
- opens an editor so that a human can prettify the changes
- appends the end result to changelog
- updates version files
- commit changes / git tag / etc
BTW, I always have to set up those tasks myself. I'm surprised some kind of standard tool does not exist. I guess everybody has their own preferences and no standard really emerged...
For customer projects it is somewhat rarer to have a decent changelog. Though, I think that Blizzard is awesome at it:
(see both new features, game mechanics balances and bug fixes).
Keeping a changelog in version control is an invitation for artificial conflicts on every single commit. (There are ways around that, but better to not keep a traditional changelog, since version control does completely make those obsolete.)
But keeping a NEWS file is an excellent practice. And when you send out a release announcement, you can include the corresponding release notes for that release.
... but it wasn't that (rather, just good arguments and suggestions).
And now I'm wondering if my first thought is a thing? And if so, how it has worked out for users.
I've tried to refrain from endorsing tools because I feel like they risk making it easy to avoid doing what I actually encourage: curating the notable changes for a release with your mushy human brain for other mushy human brains.
I know it's hard, but perhaps it's a good constraint.
The idea that you will have the forethought of knowing when writing a commit that it'll be one of the notable entries in your future changelog seems a bit far-fetched to me. And as I tried to explain, the purpose of a commit is not the same as the purpose of a changelog entry, so there's definitely tension in the re-use of copy there.
I get the instinct to automate everything. I'm just not sure this is something that should be automated. Now, an assistive tool to help maintainers review commits for missing notable changes within a changelog, that's something I could get behind.
We use Phabricator and it’s default workflow, so have a clean linear git history. Phabricator already requires strict formatting for any new diff (title, description, testing, etc). It’s built into the culture of any org using Phab to consider commits as meaningful entries in the history of the project. So it would be very straightforward (technically and culturally) to require a simple title prefix ala Changelog (ADDED, FIXED, SECURITY, etc) for each commit and have yourself a automated and meaningful log.
Not really, your changelog-from-git-log generator doesn't need to incorporate every single commit. The vast majority of commits shouldn't be incorporated in a changelog anyway, since fine-grained commits serve a different purpose. It could incorporate, for example, version-change commits whose messages serve the exact same purpose as changelog entries.
git commit -m "VERSION 1.1.0 <user readable desc of changes since 1.0.0>"
To clarify, not all of your commits need to be user-readable, since the majority of them are meant for developers -- just the sparse ones that capture the version change need to be user-readable.
Then you'd have a full commit history for the nitty gritty details and a subset of your commits would be used to generate a pretty changelog.md for everyone who wants the TLDR.
Just check out these patch notes for Patch 4.0 of Final Fantasy XIV:
Is your average player going to read all this? Probably not but it's still fascinating to see the amount of effort put in for every change, major or minor!
I write release notes for Figma and it definitely takes a lot of time, is not perfect, and becoming increasingly challenging.
Orfox issues link on f-droid is 404 I notice now.
I love it when I find something that directly relates to every day productivity. Kudos to the provider.
As a user you don't want and need all the details what changed between two releases. As a developer you absolutely need to be able to look this information up.
I'd argue these days changelog and release notes are more interchangeable than changelog and commit history. The 'NEWS' GNU-ism never really caught on, maybe because news does not imply log/history.