Version and changelog

[infinisil]

We should have a changelog and decide the versioning scheme along with it. These are some thoughts regarding that, prompted via #37.

I'm not considering changelog tools that use the Git log, because I don't think the Git log is valuable for users. I'd like to require each PR to submit such a changelog entry file (with an option to explicitly declare the PR as not changelog-worthy) (first seen here), and then using a tool to generate the changelog when it's time for a release:

• changelog-d (used by Nix since recently)
• changelogd (what I first thought Nix used..)
• Towncrier (looks very promising)
• Scriv (not as feature-complete, but does have some built-in support for GitHub releases)
• Changie (looks very promising)
• (others?)

Regarding versions, there's various versioning schemes, but I'm liking EffVer the most, and it matches the existing versions 0.1.0 and since recently 0.1.1.

I would like the automated weekly update PRs to also take care of bumping the release and changelog automatically if there's been any changes. To figure out the next version, all change entries should be tagged with the level of effort required to update (one of macro/meso/micro). Then the next version can be generated by increasing the previous one by that level. Though it's not perfect, because 100 micro changes could amount to a meso/macro change. So being able to adjust the automatically generated version number would be good too (also for an eventual 1.0.0 release).

Note that we should take some precaution to not miss PRs that might get merged during which the release/update PR is open, probably by making sure that a commit gets tagged instead of the merged commit.

[willbush]

Oh just got to this in my notifications. I just mentioned https://git-cliff.org/ in another PR. Just wanted to mention it. I don't have any strong opinions on the matter.

[infinisil]

Yeah, as also mentioned above, I'm not a fan of generating release notes from git commits, since they're often very developer-focused instead of user-focused. E.g. like 80% of recent commits shouldn't even end up in the changelog 😅. So instead I'd like to focus on tools that allow writing explicit user-focused changelog entries.

[willbush]

Just sprinkle some AI on it. /s

I think you make a good point. I haven't looked through your list yet.

[infinisil]

So I don't forget: We really need to switch away from the "merging to main triggers release" mechanism, because we can end up releasing things that weren't in the PR branch (from PR's that were merged to main in the mean time), without the respective changelogs.

A simple solution to this is to adjust the release action to target the second parent commit of the merge commit, which is the last commit in the release PR, which doesn't include the changes from main.

[infinisil]

Thinking more about this, I don't think that would be a great solution (also it would be wrong, because the PR's head is never tested, the merge into base is tested). Instead the automated release PR should automatically rebase itself and regenerate the latest changelog, such that merging it will never not include a PR merged in the meantime.

Furthermore, to guarantee that we generally make sure to only release code that passed CI: #48

[willbush]

https://news.ycombinator.com/item?id=40818781 found this interesting and this example changelog https://github.com/ratatui-org/ratatui/blob/main/CHANGELOG.md seems really good.

[infinisil]

Might be worth checking out: https://lobste.rs/s/lsqbbf/effective_changelogs