<i>The</i> standard for ChangeLog files:<p><a href="https://www.gnu.org/prep/standards/standards.html#Change-Log-Concepts" rel="nofollow">https://www.gnu.org/prep/standards/standards.html#Change-Log...</a><p>Of course, what everybody is now calling “Changelog” used to be known as a “NEWS” file:<p><a href="https://www.gnu.org/prep/standards/html_node/NEWS-File.html" rel="nofollow">https://www.gnu.org/prep/standards/html_node/NEWS-File.html</a>
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.<p>Now, we use <a href="https://github.com/twisted/towncrier">https://github.com/twisted/towncrier</a> . Every change goes through pull requests, and <i>every</i> PR <i>must</i> 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.<p>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).<p>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.
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.<p>I then take that and try to pick the top 3 or so items for use in the summary.<p>I then rewrite the summary condensing into a tweet.<p>It's a lot of work!
I have a CHANGELOG.md for all my projects.<p>Fairly boring, but useful.<p>Here's a changelog that covers about 14 years: <a href="https://github.com/bmlt-enabled/bmlt-root-server/blob/main/CHANGELOG.md">https://github.com/bmlt-enabled/bmlt-root-server/blob/main/C...</a>
My personal ranking of changelog styles I've seen in the wild:<p>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)<p>2. Breaking changes, followed by git shortlog<p>3. Developer picked highlights only<p>4. Literally just the git shortlog<p>5. A bunch of issue tracker links (especially if you later decomm that issues tracker)<p>6. Nothing
<a href="https://github.com/changesets/changesets">https://github.com/changesets/changesets</a> works well for generating changelogs.
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.<p>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.<p>¹ <a href="https://github.com/ohmyzsh/ohmyzsh/commits/master">https://github.com/ohmyzsh/ohmyzsh/commits/master</a><p>² <a href="https://github.com/ohmyzsh/ohmyzsh/blob/master/tools/changelog.sh">https://github.com/ohmyzsh/ohmyzsh/blob/master/tools/changel...</a><p>The result is something like this<p><pre><code> BREAKING CHANGES:
- 61dd368 [nats]
Rename `nsc` plugin to `nats`
Features:
- eb2147c [aws] Load profiles from credentials file (#11196)
- 4b5076b [extract] Add `pbzip2` and `pixz` (#11435)
Bug fixes:
- f1a8000 [brew] Rename `buf` alias to `bfu`
- df65835 [clipboard] Move wsl detection to higher priority (#11440)
Performance:
- ba8777f [fzf] Speed up startup on debian (#11122)
Documentation:
- 6dc6646 [git] Add missing entries and run formatter
- 0f71cfd [qrsvg] Fix command example (#11436)</code></pre>
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.<p><a href="https://twitter.com/jaredsinclair/status/633407338347634688?s=20&t=_MqF9BGHnM6SonkI4pz99A" rel="nofollow">https://twitter.com/jaredsinclair/status/633407338347634688?...</a>
Related: the "Talk Python to Me" podcast had a recent episode with guest Ned Batchelder, talking about Readme and Changelog management - <a href="https://talkpython.fm/episodes/show/395/tools-for-readme.md-creation-and-maintenance" rel="nofollow">https://talkpython.fm/episodes/show/395/tools-for-readme.md-...</a>
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.<p>[1] <a href="https://scriv.readthedocs.io/en/latest/" rel="nofollow">https://scriv.readthedocs.io/en/latest/</a>
> Companies like Slack have turned their changelogs into a form of marketing<p>To a dark place this line of thought will carry us. Changelogs are first and foremost about sharing information effectively. Never lose sight of that.