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

[CatsDeservePets]

Just to share my thoughts: I like the idea of maintaining a changelog. As mentioned in #2018 (comment), I also see potential in taking it further by introducing something like vims :h versionX or the :news command from nvim.

[ilyagr]

Off-topic: I can't hold myself back anymore. I cannot be silent. CatsDeservePets, does your username mean:

• A cat deserves a pet hamster?
• A cat deserves a pet human?
• A cat deserves a belly rub and a head pat?
• All of the above?
• All of the above and a small army of pet humans, hamsters, and other critters?
• Why only a small army? Cats deserve all of them as pets, and don't you skimp on the belly rubs either!

😸

Guess I'm easily distracted.

[CatsDeservePets]

It means whatever you want it to mean. 😼
I thought of it as silly little word play as cats do indeed deserve belly rubs and a head pat but it could also imply that they deserve to have their own pets (as in domestic animals) as well.
I never thought of the possibility of pet humans but I really like that one.

[joelim-work]

So I guess there are some points to discuss:

• Whether or not to add CHANGELOG.md to the repo
• The format to use for the changelog (e.g. from the release notes, or something copied from https://keepachangelog.com/)
• Adding a built-in command in lf to view the changelog.

I think I am in favor of adding CHANGELOG.md to the repo, but not so much for adding built-in functionality for viewing it directly inside lf.

Reading raw Markdown isn't an ideal experience for users and pandoc might be required to convert it into text form just like for doc.txt, which adds complexity to the project. Also the minimalist and configuration-driven design of lf suggests that it might be better for users to script this kind of behavior, e.g. use curl to download the changelog, and then view it using glow.

[CatsDeservePets]

Just having the file or being able to somehow curl it allows the user to implement their own changelog related commands (one of the strengths of lf).

[joelim-work]

Regarding the format I was thinking of changing it slightly to be closer to the format given in https://keepachangelog.com/:

# Changelog

All changes observable to end users should be documented in this file.

The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and should contain the following sections for each release:

- `Changed`
- `Added`
- `Fixed`

## r36 (Unreleased)

### Changed

- A breaking change was made (#100).
- Another breaking change was made (#101).

### Added

- Something new was added (#102).
- Something else new was added (#103).

### Fixed

- A bug was fixed (#104).
- Another bug was fixed (#105).

Some minor points to discuss:

• Originally the sections were listed as Breaking/New/Fix in the release notes, but I think it is more natural to use the terms Changed/Added/Fixed. However I plan to keep the labels and milestones as they currently are.
• Issue links won't work when clicking directly from the Markdown file. However they should work when clicking from the release notes, which will end up being copied from this file anyway, so I don't think this is an issue.
• I am not sure users will care about who contributed which change, so maybe it's more concise to just omit it. Anyone who is interested can click on the issue to see the author. But I don't mind adding it in if contributors really want to be recognized.

[joelim-work]

This has now been added in #2027