Implement a commit message linter

[klardotsh]

Context and Argument

I noticed this in both my own work and in this repo: commit messages, if not enforced to follow a given style, expand to fill the possibilities the world could possibly allow for them to take. Which is to say: we have a heck of a lot of styles going on. Let's take a quick curated look at recent additions to master:

• 225087c, "remove not-implemented keycodes from docs"
• 0477b56, "docs(readme): remove scary banner about maintainership, reword chat b..." (the elipsis can be expanded in the GitHub UI, I'm leaving it here to prove a point)
• e2681a2, "Move quickpin docs"
• 296e4a3, "Git rid of hard reference to <long url here>"
• 885359a, "docs update"

(Calling these out is NOT intended as a personal attack, and I intentionally included one of my own in this list to pick on :smile:)

From top to bottom:

• The top one is excellent. Tells me exactly what happened without too much detail.
• The second one, while informative and specific, is too long because GitHub can't render it all without expanding the line (which requires JavaScript). I believe that cutoff is 72ish characters, which also means that it will flow right off the side of the screen in smaller terminals (well, it'll wrap to the next line, but now that comes with its own oddities)
• The third one is quick and to the painless. Moving on.
• The fourth one includes a bonkers-long URL which also flows right off the side of the screen. Thankfully, that's the point of the commit anyway: "stop hard-coding this specific URL". It's just word.
• The fifth one unfortunately doesn't tell me much about what happened at this point in the history. Which docs updated? Do I care?

Proposal

I'd like to adopt some standardized commit message style, and a linter to enforce that all commits in a PR follow that spec. I've done some thinking over the past few weeks about some personal dev habits of mine, and I think in part thanks to that reflection, I might stray away from my go-to style from the past ~3 years, Conventional Commit, in favor instead for Chris Beam's Seven Rules.

The seven rules are as follows:

1. Separate subject from body with a blank line
2. Limit the subject line to 50 characters
3. Capitalize the subject line
4. Do not end the subject line with a period
5. Use the imperative mood in the subject line
6. Wrap the body at 72 characters
7. Use the body to explain what and why vs. how

I'll let you all read Chris's blog post about why those rules make sense. Particularly, in contrast to Conventional Commit, these rules make no attempt to hint at the gravity of a change (which, in Conventional Commit codebases, is often used to dictate how to increment a Semantic Version, perhaps with a release bot's help. Since we are a trunk-only project with no stable releases (yet?), such metadata is simply line noise for us anyway.

For enforcing Chris's Style (I have no idea if there's a proper name for this), I might propose a GitHub Action based around the ruleset, https://github.com/mristin/opinionated-commit-message. While we one day might leave GHA for CI, for now, it gets something going. The codebase might be forkable in a future GHA-less world, but does clearly seem to tie into GitHub's APIs, so this may be a thing we'd have to take into our own hands when and if that's a concern (or adopt another third party tool, if one exists).

So.....

Thoughts?

[xs5871]

For what it's worth: I support that notion completely. The 7Rules make a lot of sense for incremental, non-breaking commit messages (linguistic friction about 'capitalization, but not punctuation' aside). They are the more natural guidelines for 'good commits' in my opinion. If I'm not mistaken, the formatting guidlines are also hinted at with bare git, and i.e. fugitive. For (github-)PR headers, I think I'd go more towards the Conventional Commit style -- they suggest more of a summary. Githubs PR process conflates the two, obviously. That's a seperate issue which I may want to personally imporve on.

[xs5871]

On that subject: We could discuss require squashing PRs, so that we don't get those multiple "fix linter" commits in a row.

[grasegger]

I am all for conventional commits too, it proofed useful for us at work and if followed by all it makes it easy to read a log.

https://www.conventionalcommits.org/en/v1.0.0/

There is also a lot of tooling around it.

I am also all for squashing commits.

Just my 2ct, for what it's worth :D