The Subtle Art of the Changelog | Hacker News Reader

The Subtle Art of the Changelog

commandbar.com

97 pointsGarethX27 comments

The standard for ChangeLog files:

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

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.

... yup, first tasks are going through all issues resolved and all commits/PRs merged and cross check.

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.

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

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!

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

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.

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

Congratulations if v3.0.0!

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.

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

https://github.com/changesets/changesets 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.

Would be a cool (but painful to do) analysis to look at whether this happens and at what scale companies throw in the towel.

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.

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/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)

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

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

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/

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

I copy/paste the template from:

https://keepachangelog.com

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

Git commit messages are written under time pressure, change logs allow you to refactor the history and clarify things as facts become known.

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/

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.

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.

Reply on news.ycombinator.com