9 ms·

The Subtle Art of the Changelog

97 points by GarethX 4y ago

anonymoose33282 4y ago
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.
- GarethX 4y ago
  Yeah, in times of auto-downloading updates, I can see why many don't, but I certainly appreciate it when they do.
Macha 4y ago
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) 6. Nothing
nickcw 4y ago
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. It's a lot of work!
- sgbeal 4y ago
  > It's a lot of work! 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).
- account42 4y ago
  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.
olddustytrail 4y ago
When everything is in git and you have the log anyway, is there really any use for a changelog?
- mikewarot 4y ago
  Git commit messages are written under time pressure, change logs allow you to refactor the history and clarify things as facts become known.
- pan69 4y ago
  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. https://www.conventionalcommits.org/en/v1.0.0/ https://www.conventionalcommits.org/en/v1.0.0/
- misnome 4y ago
  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.
- thebigspacefuck 4y ago
  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.
teddyh 4y ago
The standard for ChangeLog files: https://www.gnu.org/prep/standards/standards.html#Change-Log-Concepts 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 https://www.gnu.org/prep/standards/html_node/NEWS-File.html
dazzeloid 4y ago
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.
- GarethX 4y ago
  That's what I respect about Citymapper in the linked article - they're 11 years in and still putting in the effort to their updates.
misnome 4y ago
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 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.
- waynesonfire 4y ago
  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.
  - silon42 4y ago
    ... yup, first tasks are going through all issues resolved and all commits/PRs merged and cross check.
ChrisMarshallNY 4y ago
I have a CHANGELOG.md for all my projects. Fairly boring, but useful. Here's a changelog that covers about 14 years: https://github.com/bmlt-enabled/bmlt-root-server/blob/main/CHANGELOG.md https://github.com/bmlt-enabled/bmlt-root-server/blob/main/C...
- jayknight 4y ago
  Congratulations if v3.0.0!
  - ChrisMarshallNY 4y ago
    I actually have almost nothing to do with it, anymore. The first ten years are all me, but a new team has taken the reins, and are doing fantastic. 3.X is 100% theirs.
deleted 4y ago
[deleted]
haihaibye 4y ago
I copy/paste the template from: https://keepachangelog.com https://keepachangelog.com
buerkle 4y ago
https://github.com/changesets/changesets https://github.com/changesets/changesets works well for generating changelogs.
andreareina 4y ago
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. [1] https://scriv.readthedocs.io/en/latest/ https://scriv.readthedocs.io/en/latest/
Calzifer 4y ago
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. ¹ https://github.com/ohmyzsh/ohmyzsh/commits/master https://github.com/ohmyzsh/ohmyzsh/commits/master ² https://github.com/ohmyzsh/ohmyzsh/blob/master/tools/changelog.sh https://github.com/ohmyzsh/ohmyzsh/blob/master/tools/changel... The result is something like this 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)
raphael_l 4y ago
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. https://twitter.com/jaredsinclair/status/633407338347634688?s=20&t=_MqF9BGHnM6SonkI4pz99A https://twitter.com/jaredsinclair/status/633407338347634688?...
toyg 4y ago
Related: the "Talk Python to Me" podcast had a recent episode with guest Ned Batchelder, talking about Readme and Changelog management - https://talkpython.fm/episodes/show/395/tools-for-readme.md-creation-and-maintenance https://talkpython.fm/episodes/show/395/tools-for-readme.md-...
kaycebasques 4y ago
> Companies like Slack have turned their changelogs into a form of marketing 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.

97 points by GarethX 4y ago

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.

GarethX 4y ago
Yeah, in times of auto-downloading updates, I can see why many don't, but I certainly appreciate it when they do.

Macha 4y ago

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) 6. Nothing

nickcw 4y ago

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. It's a lot of work!

sgbeal 4y ago
> It's a lot of work! 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).
account42 4y ago
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.

olddustytrail 4y ago

When everything is in git and you have the log anyway, is there really any use for a changelog?

mikewarot 4y ago
Git commit messages are written under time pressure, change logs allow you to refactor the history and clarify things as facts become known.
pan69 4y ago
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. https://www.conventionalcommits.org/en/v1.0.0/ https://www.conventionalcommits.org/en/v1.0.0/
misnome 4y ago
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.
thebigspacefuck 4y ago
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.

teddyh 4y ago

The standard for ChangeLog files: https://www.gnu.org/prep/standards/standards.html#Change-Log-Concepts 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 https://www.gnu.org/prep/standards/html_node/NEWS-File.html

dazzeloid 4y ago

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.

GarethX 4y ago
That's what I respect about Citymapper in the linked article - they're 11 years in and still putting in the effort to their updates.

misnome 4y ago

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 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.

waynesonfire 4y ago
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.
- silon42 4y ago
  ... yup, first tasks are going through all issues resolved and all commits/PRs merged and cross check.

ChrisMarshallNY 4y ago

I have a CHANGELOG.md for all my projects. Fairly boring, but useful. Here's a changelog that covers about 14 years: https://github.com/bmlt-enabled/bmlt-root-server/blob/main/CHANGELOG.md https://github.com/bmlt-enabled/bmlt-root-server/blob/main/C...

jayknight 4y ago
Congratulations if v3.0.0!
- ChrisMarshallNY 4y ago
  I actually have almost nothing to do with it, anymore. The first ten years are all me, but a new team has taken the reins, and are doing fantastic. 3.X is 100% theirs.

deleted 4y ago

[deleted]

haihaibye 4y ago

I copy/paste the template from: https://keepachangelog.com https://keepachangelog.com

buerkle 4y ago

https://github.com/changesets/changesets https://github.com/changesets/changesets works well for generating changelogs.

andreareina 4y ago

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. [1] https://scriv.readthedocs.io/en/latest/ https://scriv.readthedocs.io/en/latest/

Calzifer 4y ago

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. ¹ https://github.com/ohmyzsh/ohmyzsh/commits/master https://github.com/ohmyzsh/ohmyzsh/commits/master ² https://github.com/ohmyzsh/ohmyzsh/blob/master/tools/changelog.sh https://github.com/ohmyzsh/ohmyzsh/blob/master/tools/changel... The result is something like this 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)

raphael_l 4y ago

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. https://twitter.com/jaredsinclair/status/633407338347634688?s=20&t=_MqF9BGHnM6SonkI4pz99A https://twitter.com/jaredsinclair/status/633407338347634688?...

toyg 4y ago

Related: the "Talk Python to Me" podcast had a recent episode with guest Ned Batchelder, talking about Readme and Changelog management - https://talkpython.fm/episodes/show/395/tools-for-readme.md-creation-and-maintenance https://talkpython.fm/episodes/show/395/tools-for-readme.md-...

kaycebasques 4y ago

> Companies like Slack have turned their changelogs into a form of marketing 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.