We used to... somewhat attempt manual changelogs. Every time it came to a release the release manager would ask around for what the key changes were, and we usually ended up with only a couple of entries.
Now, we use https://github.com/twisted/towncrier . Every change goes through pull requests, and every PR must have a newsfragment file - and we enforce this with a test that fails if it isn't present (with convenience functions of rewriting the number to match the PR if you name the news file XXX.{category}). If it's not a user-facing change, then we just have a category that is ignored.
On releases (or on individual PRS along the way), the release manager generates the changelog, but also edits them into a relatively coherent style (or rewrites developers news fragments along the way).
Every change has a note written aimed at the user. Every entry in the changelog has a link to the relevant PR or commit. We have much better changelogs now.
the release manager would ask around? how about paying attention and taking notes as development and product discussion take place? Instead, the developers are having to do the release managers job.
I'm one of the people who always glances at changelogs when downloading an app for the first time, and I appreciate when developers go beyond 'Bug fixes and minor improvements' to at least list a couple concrete things that were added. I'm sure I'm in the minority, but I like the extra effort.
When I make rclone releases I usually spend an hour or two taking the git log, removing irrelevant stuff and rewriting messages to make them make sense from a users point of view.
I then take that and try to pick the top 3 or so items for use in the summary.
I then rewrite the summary condensing into a tweet.
But it's a godsend for those who care about it (as you obviously do or you wouldn't put in the effort). It was only through a recent changelog entry in Emscripten that i was able to locate a truly obscure bug in the sqlite3 wasm builds (triggered by a default-value change in Emscripten's stack size). Without that hint i'd _still_ be searching for the cause of that bug (more than a month later).
I have started to update the changelog file with each commit (that does something changelog-worthy) just so that I don't have to do all that work when releasing a new version.
My personal ranking of changelog styles I've seen in the wild:
1. Categorised list of human-written points, e.g. breaking changes/features/bugfixes for developer facing software, features with overview of how to use them for end user facing (see vs code)
2. Breaking changes, followed by git shortlog
3. Developer picked highlights only
4. Literally just the git shortlog
5. A bunch of issue tracker links (especially if you later decomm that issues tracker)
I feel like a lot of companies put effort into their changelog in the early days when they're trying to cultivate their first users and know every user personally. But then I see them inevitably fall into the "bug fixes and performance improvements" laziness.
Would be a cool (but painful to do) analysis to look at whether this happens and at what scale companies throw in the towel.
oh-my-zsh has a quite interesting changelog system. Every commit¹ summary is prefixed in a standardized way which is later used to generate² a nicely formatted and categorized list of changes.
Does anyone know what was behind this link? It was mentioned as "too much of a good thing", but seems that account has been deactivated and the tweet is gone.
We've recently started using scriv[1] to manage the changelog and I'm a fan. Each branch gets its own changelog fragment and when we're ready to cut a release they're all merged into a single entry in the log.
Different audiences. A Changelog is read by the users of your software, the commit message by the developers. It's rare that a commit message is suitable for both.
When you want to publish your changelog to your users you probably want to have some standards around your commit messages and when you do, from the commit history you can then automate the creation of a changelog.
Maybe I’m missing something but git releases are a pain to search through. A changelog is searchable or I can scroll through and figure out where breaking changes or a particular bug was fixed.
https://www.gnu.org/prep/standards/standards.html#Change-Log...
Of course, what everybody is now calling “Changelog” used to be known as a “NEWS” file:
https://www.gnu.org/prep/standards/html_node/NEWS-File.html