Skip to content

Conventional Commits

Jump to bottom
Ashley Childress edited this page Sep 13, 2025 · 1 revision

✨ Commitlint + Conventional Commits & RAI Footers: Why Your Messages Matter

🎯 What is Commitlint?

Commitlint is a tool that lints commit messages based on a set of rules. Think of it as a spellchecker for your git history—except instead of catching typos, it catches style violations and missing structure.

At its core, Commitlint makes sure every commit message follows a predictable pattern. That predictability pays off later when generating changelogs, automating releases, and just trying to read what happened six months ago without crying into your keyboard.

Commitlint itself doesn’t enforce the rules—you need a git hook manager for that. In our setup we’ll be using Lefthook (coming soon!)

📜 Conventional Commits

Commitlint’s most common configuration is @commitlint/config-conventional, which enforces the Conventional Commits spec.

The Conventional Commits format looks like this:

<type>(<scope>): <subject>

<body>

<footer>
  • Type — feat, fix, docs, etc.
  • Scope — area of code affected
  • Subject — short description (72 chars max)
  • Body — why & how
  • Footer — metadata: Signed-off-by, BREAKING CHANGE, RAI footers

Example:

feat(auth): add JWT validation to login endpoint

The login flow now validates JWT tokens against our auth service.
This ensures expired tokens are rejected and refresh flow is enforced.

Co-authored-by: ChatGPT

Then use the --signoff flag to add the Signed-off-by trailer or, even better, use a GPG signature instead (that get's you the nifty "Verified" badge on GitHub that you'll see next to all my commits):

git commit -m "feat(auth): add JWT validation to login endpoint" --signoff

🧠 RAI Footers & Transparency

I’ve written more about this in my blog post Can We Set the Record Straight? AI, Content, and a Bit of Sanity.

The takeaway is simple: disclosure matters. AI shows up everywhere in workflows now, and pretending it’s not there doesn’t help anyone. Conventional Commits give us a built-in structure for making AI involvement explicit, right inside the commit footer.

In that post (and especially in the comments), I explored the idea of levels of AI involvement:

  1. "Human-content" means no AI at all
  2. "Commit-generated-by" if Copilot or friend just wrote the commit
  3. "Assisted-by" means that AI assisted with 1%-33% of the content
  4. "Co-authored-by" means AI coded roughly half of the content, 34%-67%
  5. "Generated-by" means the content is majority AI, 68%-99% (because you still had to prompt it)

It’s not about policing creativity—it’s about accountability. Adding RAI footers means future readers (including your future self) can tell whether AI helped write something, and to what degree. That level of traceability is exactly why we configure Commitlint to enforce signature and trailer rules.

🔧 Our Custom Rules

We build on conventional commits, with stricter rules to support RAI footers and long-term clarity:

  • Require lowercase for type, scope, subject
  • Require a scope on every commit (you can turn it off if you want, but I strongly recommended getting in the habit—your changelogs will thank you later)
  • Require a body section
  • Enforce max lengths (72 chars header, 100 chars body/footer)
  • Require blank line before the body
  • Require Signed-off-by trailer in footer
  • Signature and trailer rules are marked as warnings (so AI tools don’t try to autofill them), but the hooks will be configured to fail on warnings, blocking unsigned or undisclosed commits

🚦 Hook Setup

Commitlint only validates—it doesn’t block commits by itself. That’s where hooks come in.

We’ll be using Lefthook. Details on configuration coming soon!

Lefthook will run Commitlint on every commit and fail if the message is missing required disclosure or signature footers.

🌟 Why This Matters

Conventional Commits + Commitlint + RAI footers create a foundation of clarity, trust, and accountability.

They ensure every commit message is useful, every change is traceable, and every AI contribution is disclosed responsibly. That’s not bureaucracy—that’s good engineering hygiene.

This page was generated with the help of ChatGPT as directed by Ashley Childress on Friday September 12, 2025

This page was generated with the help of ChatGPT as directed by Ashley Childress

Clone this wiki locally