chore: conventional commits

[sandr01d]

Check list

• I have performed a self-review of my code
• I have commented my code in hard-to-understand areas
• I have added unit tests for my code
• I have made corresponding changes to the documentation

Description

As discussed in #479, we'd like to use conventional commits for this project going forward. To help with this, this PR

1. Adds a CI job to validate commit messages of PRs using commitlint.
2. Modifies the release job to generate a richer changelog using git-cliff.

I'm using both of these tools in my dayjob, so I'm already familiar with them.

commitlint seems to be the goto solution for linting against conventional commits and from my research seems to be pretty much the only option. The downside of commitlint is that it is only available through npm, which means we have to first install npm and then commitlint in the workflow - which is a bit slow. I tried using the setup-node action, as outlined in commitlints docs, but this action seems to assume a Node.js based project and complains about the missing package-lock.json.

I decided to go with git-cliff, because I've had a very good experience using it and because I know it to be very flexible. Another big plus IMO, is that it can also be installed locally, which makes testing/troubleshooting a lot easier. I've created a release on my fork, so you can get an impression about how the changelog would look like. Ignore that most changes are currently listed under "Other". This is only the case because those commits do not follow conventional commits yet.

Type of change

• Bug fix
• New feature
• Refactor
• Breaking change
• Test
• Documentation change
• CI

Test environment

• Shell
  • bash
  • zsh
  • fish
• OS
  • Linux
  • Mac OS X
  • Windows
  • Others:

[cjappl]

LGTM! Very cool.

(1000% outside the scope of this review)

Looking through our ci.yaml and seeing it get more complex, at some point it may be nice to move some of that to a Makefile that devs can run locally.

I have seen situations where the ci becomes some beast that is un-runnable locally and hard to troubleshoot. Stuffing it in a Makefile and having ci be something like make changelog helps squash that a bit.

[carlfriedrich]

@sandr01d Thanks a lot for your work on this! I haven't used Cliff before but like both its simplicity and flexibility.

I have just a few comments concerning the commit parsers, but none of these are blocking.

From my perspective this can be merged. Eventual adjustments can be made later when we have some experience on how all this performs in practice.

I also second the comment from @cjappl, it's a good idea to outsource the individual commands into small scripts that can be run locally, but that can indeed be done in a separate PR.

[sandr01d]

Thanks for the quick reviews @cjappl @carlfriedrich. I've updated based on your suggestions.
I agree that moving things out of the workflow is a good idea, but out of scope for this PR. I'd recommend just over make. I find it easier to work with and there is a GitHub Action available for it too.

[sandr01d]

Also one additional change, I've updated Dependabot to use a lower case prefix, which is the common case for conventional commits.

[carlfriedrich]

@sandr01d Great, thanks for the update. From my side this is merge-ready.

I agree that moving things out of the workflow is a good idea, but out of scope for this PR. I'd recommend just over make.

IMO we don't need any external tool at all. Why not use simple shell scripts for these things? Especially since we already have proper tooling for shell scripts in place.

[cjappl]

I'm more pro make or shell scripts over just. Simply because every unix machine ships with it by default and it doesn't take any external configuration or installation. I think there's value in using standardized unix tools wherever possible.

Either is fine by me, I think it only depends on how many inter-step dependencies we have (more, make, less, shell scripts).

[sandr01d]

IMO we don't need any external tool at all. Why not use simple shell scripts for these things? Especially since we already have proper tooling for shell scripts in place.

Sure that'd work for me too.