Changelog-Driven Releases | Hacker News Reader

Changelog-Driven Releases

mathieularose.com

30 pointsthunderbong13 comments

My problem with maintaining a changelog during development is it can serve as a source of merge conflicts. Instead, I follow Covnentional Commit style and manually write my changelog entries based on the commits. I have a tool [0] that can show me the relevant commits for a package in my repo and automates the entire release process, including doing sanity checks.

I also feel like releasing from CI is hard, especially if you have multiple packages in a repo [1], including

- You can't as easily introspect the process

- You can't as easily recover from failure

- Getting a lot of the nuance right, like handling releases concurrent to merging of PRs, is difficult

- When the workflow is an ever-present "release PR" that you merge when ready has issues with selecting which packages to release and at what version

I have been considering making a tool to generate changelogs from fragments. Been keeping notes at https://github.com/epage/epage.github.io/issues/23

[0]: https://github.com/crate-ci/cargo-release

[1]: https://github.com/MarcoIeni/release-plz/discussions/1019

I don't really like writing the change log automatically from commits. I think those both have a slightly different audience and thus need different wording.

I know the frustration of merge conflicts on the change log file.

Right now, I'm creating change logs by hand which is time consuming to do on release time. I'm considering switching to using towncrier or something similar, where you have a changes dir with one file per change for creating change logs --> https://towncrier.readthedocs.io/

The towncrier approach is similar to what we do at work. We have the addition that the individual changelog files say their scope (major, minor, or patch), and we use that to automatically compute the next version number.

  version.txt
    1.0.0
  CHANGELOG
    # 1.0.0
    * Initial release
  changelogs/add-foobar-api.md
    minor: Add a new API call `foobar`
  changelogs/improve-baz-perf.md
    patch: Improve the performance of the `baz` API call

In the changelog compilation step it works out that the largest scope is minor, so the version of the next release is bumped from 1.0.0 to 1.1.0, and you end up with:

  version.txt
    1.1.0
  CHANGELOG
    # 1.1.0
    * Add a new API call `foobar`
    * Improve the performance of the `baz` API call

    # 1.0.0
    * Initial release

It works great, especially for large teams. You don't end up with lots of merge conflicts on the CHANGELOG file. The people writing the change get to describe the scope of the change (and that can be reviewed in the PR), rather than the person doing the release having to guess from the descriptions. Developers never have to worry about whether someone else has already bumped the version number or not.

I also use a similar approach for my open source Python automation project, alkymi: https://github.com/MathiasStokholm/alkymi/blob/develop/CHANG...

In addition to the author's comments, I would suggest also using the format from https://keepachangelog.com/en/1.1.0/ (more sub-headings, e.g. "added").

Lastly, pruning the CHANGELOG upon adding and removing stuff again is a great idea to keep entries meaningful for the reader.

I don’t release OSS software so this is a peanut gallery comment. But I don’t understand the preoccupation with changelog-driven anything. The changelog is the source of truth? The VCS log is a guaranteed sort of truth. Now having a single file that everyone else can read is convenient. But I don’t quite understand being so motivated to go through a lot of hoops (like automating the changelog, dealing with merge conflicts from multiple contributors when appending to one changelog file). What I would naively do if I wanted to automate the changelog:

- Make a script that creates the Git (or whatever) tag and also appends everything new to the changelog via something like git-shortlog

Using a GitHub workflow for that seems complicated (yaml and all).

But if I wanted a curated changelog? I guess I would write it semi-manually: maybe some scripting around the git-log (for relevant pieces) and sprinkled in with either deletions of things that are too technical or nitty gritty + additions of things that the user might care about (but might be obvious from the log for the developers, i.e. not really spelled out there).

But I wouldn’t wanna use something like “conventional commits”. Mostly because I don’t like the convention it uses. But also because it seems to rely too much on the log, i.e. you end up with duplication. (A changelog that closely mimics git-log is convenient (again) but I also would want to sprinkle in some end-user specific writings.)

Aah, well maybe (hopefully) I get to develop some library or something which I feel deserves a changelog someday. Maybe when it gets more than two GitHub stars.

> Make a script that creates the Git (or whatever) tag and also appends everything new to the changelog via something like git-shortlog

I've seen projects that do this, and it's almost completely worthless. If I wanted to read all the commits, I'd go read the commits; I came to the changelog because I wanted to know if anything important changed.

I agree. The changelog should be curated.

On any release - which means a tag containing the version number - I first check the latest version number in the changelog/release notes against the version number in the tag and if they aren't the same CI throws an error. If the versions match, the latest changelog/release notes are also extracted and used as the release text (for example on GitHub or sending internal emails or wherever the release information is needed).

Seconding this. Sounds trivial and stupid but just having an an automated check for a corresponding changelog entry before acutally versioning/releasing is a huge improvement.

If the release management/tagging is often done from developer machines instead of happening in/via CI, I'd also advise checking for a clean worktree (no uncomitted changes) before allowing a release.

> I'd also advise checking for a clean worktree (no uncomitted changes) before allowing a release

Oh yes, this had been a source of problems for us in the past too.

I was initially wondering if this:

    ## 1.29 (2021-01-16)
      * Show total time in summary section
      * Remove "Time" from summary section

...was supposed to be an example of how not to do it, but I assume it's actually meant as a showcase of what the tool can do (overlooking the two changelog entries that apparently cancel each other out?)

No, I guess that's just a joke.

That's the script: https://github.com/larose/utt/blob/e31c7340cd4c151b7a5bfa004...

Edith wanted to add that that's the actual changelog of utt: https://github.com/larose/utt/blob/master/CHANGELOG.md

Oops, that's just bad writing from me. Should be clearer now that they aren't cancelling each other. Thanks!

Reply on news.ycombinator.com