From ca2ee9a5546e791e4c458db5d12d815bb2cfee77 Mon Sep 17 00:00:00 2001 From: Amolith Date: Thu, 23 Oct 2025 08:12:44 -0600 Subject: [PATCH] docs: don't bury the lede, polish --- README.md | 24 ++++++++++++++++++------ 1 file changed, 18 insertions(+), 6 deletions(-) diff --git a/README.md b/README.md index 661874aa1ef1ed9c0df0d8b8b1841796d9e31aec..a56a8e2fd8d2182ed0368d1ca620e1286ba9735b 100644 --- a/README.md +++ b/README.md @@ -10,14 +10,26 @@ SPDX-License-Identifier: CC0-1.0 [![Go Report Card](https://goreportcard.com/badge/git.secluded.site/formatted-commit)](https://goreportcard.com/report/git.secluded.site/formatted-commit) -CLI tool that requires conformance with the Conventional Commits specification -through flags, made for LLMs and not really for the operators (but I guess you -can use this directly if you want). Operators would likely prefer, as the author +CLI tool that produces commits following the Conventional Commits specification +through flags, made for LLMs and not really their operators (but I guess you can +use this directly if you want). Operators would likely prefer, as the author does, [meteor](https://github.com/stefanlogue/meteor). -`formatted-commit` enforces a 50-character subject limit and sanitises/wraps the body at 72 -characters. I might make that configurable. Idk. It's a loose standard held by -projects like the Linux kernel and I try to stick to it. +I've found that LLMs consistently fail to + +- Format trailers correctly: they add too many newlines between trailers, which + breaks tools like `git interpret-trailers` +- Include proper scope notation +- Follow the loose 50/72 subject/body standard held by projects like the Linux + kernel. I try to stick to it, but LLMs writing badly-formatted commit messages + means rewording work for me once they're done. + +`formatted-commit` enforces all of this. Where possible, we "correct" the +model's input. Where that's less possible, we error. For example, instead of +requiring the model wrap body text at 72 columns, we let it write whatever body +it wants and wrap it ourselves. We can't really fix the subject, so +`formatted-commit` emits an error when the subject is too long with clear +indication of where the 50-character cut-off is. ## Installation