Maintaining a changelog

[joelim-work]

From #1407, we discussed the possibility of maintaining a separate CHANGELOG.md file in the repo, however at the time it was rejected because:

• It contained GitHub specific information (users and issue/PR IDs) - I have no idea if this is really an issue or not since these are seen in commit messages anyway.
• It would have to be updated frequently as new changes are added, especially if there is a section for unreleased changes.

As a result, we have just been simply adding the release notes into the description for each release. This works well for users who upgrade regularly and just want to see what is new in the latest release, however it is not easy to view changes across all releases in a single big list.

I suppose it's possible to just maintain a CHANGELOG.md in the repo, and then release notes can either be manually copied (or automatically via some GitHub action) when generating a new release. But for the time being I'm also happy to keep things the way they are now.

In any case I ended up writing a script which uses GitHub API calls to generate such a changelog if I ever need it. This can be piped into glow -p to make it look nicer.

#!/bin/sh

export GH_PAGER=''

gh() {
    # Run until success, sometimes this fails due to API rate limiting
    while ! command gh "$@" 2>/dev/null; do
        true
    done
}

gh release list -L 9999 --json name -q '.[].name' | while read -r release; do
    printf '# Release %s\n\n' "$release"
    gh release view --json body -q .body "$release"
    printf '\n\n'
done