Will we use Keep a Changelog?

[marxin]

Just wanted to suggest if we could start using the format since the new release of Wild: https://keepachangelog.com/en/1.1.0/ ?
Seems to me we're pretty close, where the biggest difference would be the categorization of the changes?

What do you think?

[davidlattimore]

I'd be open to that. Although from a user's perspective some feature additions can appear as bug fixes, but I guess we can try to make a judgement call

[mati865]

Do you want to also use Conventional Commits, so the changelog can be easily generated with tools like Cliff?

[davidlattimore]

I'm open to doing that if others think it's a good idea. Especially if it can be optional, with the non conforming entries cleaned up at release time. I want it to be as easy for new contributors as possible. Actually, I guess we can edit the commit message when we squash the changes, so that helps a bit.

[mati865]

I haven't used it with GitHub, but apparently it can even use PR labels: https://git-cliff.org/docs/tips-and-tricks#use-github-pr-labels-as-groups. So That should be even easier to manage.
Regardless of that, you can configure whether commits that don't follow Conventional Commits are also included: https://github.com/orhun/git-cliff/blob/85cc05dda8a3b96864cbb62ca648275a1323e2fc/config/cliff.toml#L42

I don't have a problem with using that convention, but I don't want to force others. If generation from the labels work well, everyone could use whatever style they like.

[marxin]

Yes, I think the Conventional Commits would nicely match with the Changelog format. For the beginning, I would just start by formatting the Changelog format (that is pretty close to Keep a Changelog format even now) in the next release. Apart from that, I would make a recommendation about the Conventional Commit format in PR template - what do you think?

[davidlattimore]

Sounds good to me. I guess the PR description, and thus the PR template will only make a difference if we squash the PR, although I have switched to mostly squashing even for single-commit PRs, so that might be OK.

[mati865]

Made an attempt with git-cliff, but I'm not sure whether it actually helps: #1256

[davidlattimore]

I guess perhaps our first step should be to figure out what groupings we want. Some possible ideas are features, fixes, tests, performance, refactoring, docs, linker-diff. Fixing tests, I think should go under tests rather than under fixes - at least where there wasn't a bug in the linker and it was just the test that was broken. Typo fixes, I suspect we should just skip. I expect for our first release, we'll need to do a lot of manual adjustments, since we haven't been prefixing our commit messages until just recently.

[mati865]

It could be done by retroactively relabelling pull requests, but I don't know if it will work for pull requests that were rebase-merged instead of squash-merged.
I kind of like the default config because it's more readable, "Keep a Changelog" format is quite limiting.

[davidlattimore]

If the default config is more readable, then I'm all for using that as a starting point instead of "Keep a Changelog". I probably wouldn't worry about retroactively labelling pull requests, but instead just manually edit the changelog after git-cliff generates it - move stuff around, add extra groupings etc.

[marxin]

If the default config is more readable, then I'm all for using that as a starting point instead of "Keep a Changelog".

Works for me! Thanks for the investigation @mati865.

[mati865]

Perhaps I should elaborate more on what I don't like about "Keep a Changelog" format. It doesn't distinguish "importance" of a change, so it works well only for the most important changes or the highlights. When there are dozens of entries under a single section, it takes more willpower to keep reading it, looking for interesting things.
A packager will be more interested in different changelog entries compared to a regular user, but in the end it's just a matter of convenience. I think #1264 addresses that well.

[mati865]

With the new release drafted I think we can close this issue.