I find that the CC structure helps me scan a list of recent commits, e.g. when squashing something into a past commit or trying to find where to navigate.
I don't spend a lot of time on trying to come up with scopes etc, I just make sure that my commit does one thing that fits the label.
Alternative: I do a lot of commits just marked "wip" as I go, then when I'm ready to consider a PR, I rebase my branch into something for public consumption. Some commits will get thoughtful messages when warranted, others will get one line, and the PR description will tie it all together with screenshots and links to the most interesting parts.
(On a good day, that is. Though even on a bad day I don't let "wip" commits into the main branch.)
> There's no need to justify that your changes are "in accordance with best practices", tell a story about "ongoing efforts" (unless you actually have other recent commits that you want to group together like that conceptually), etc.
LLMs are very prone to generalisation and marketing language like this. Despite being sycophants, they are also trained to speak as if they constantly have to justify and persuade.
This is called out in the Wikipedia meta I linked to in another comment. They're great red flags to look out for in any writing; humans, myself included, often used this kind of lazy construction!
If we assume, as many do, that we are going to delegate the work of "understanding the code" to AI in the coming years, this surely becomes even more important.
AI writing code and commit messages becomes a loop divorced from human reasoning. Future AIs will need to read the commit history to understand the evolution of the code, and if they're reading poor summaries from other AIs it's just polluting the context window.
Commit messages are documentation for humans and machines.
I applaud your desire to write better commit messages and not be lazy. Not every commit deserves the attention, but being able to turn on "I am definitely going to leave a precise record for the next person to see this diff" is a great skill to have.
However, I feel like your approach here is a little backwards. By getting the AI to come up with the commit messages, you're actually removing the chance for the human, you, to practise and improve.
I'm a real fan of Kahneman's "thinking fast" and "thinking slow" paradigm. By asking the human to review and approve the commit message, you're allowing them to "think fast", instead of doing the challenging, deliberative "thinking slow" of actually writing what you mean.
While getting the LLM to ask you questions about what you did and why is better than just one-shotting the commit message from the diff, it still lets you reply "reactively" and instinctually, using your "fast" gut thinking, instead of engaging the slower attentive processes required to write from scratch.
Now there are a couple of other posters here critiquing the commit messages in this repo's history. I think that's fair, but by your own admission you are learning, and this is a small and new project! Probably most commits should be along the lines of "getting a thing working", not essays about the intricacies of character encoding:
But the commits we can see are already demonstrating some of the pitfalls of LLM generated language.
From a recent commit,
"This update enhances user interaction by explicitly addressing scenarios with large diffs, directing users towards feasible actions and maintaining workflow continuity."
This comes after a detailed breakdown of the diff. It is too vague to stand alone without the preceding detail (e.g. 40k character limit) but also doesn't explain them. Why 40k characters? Why any limit at all? Words like "enhances" and "feasible" are filler - be concrete instead.
This article on wiki has fantastic advice about ways that LLM writing fails, more along the lines of what I've just pointed out:
Writing well is hard, never "effortless" as your readme advertises. Sadly, good results have to come from hundreds of hours of hard and uncomfortable work. Truth is rare and precious and difficult to come by, and even when we glimpse it, turning it into words is a whole nother story. I hope you can continue to develop this tool to help you learn and train your own writing, rather than avoid it.
More drive-by criticism of your commits, meant in a sincere attitude of helping you learn.
As best I can tell, lots of your commits seem to be including several unrelated changes.
This means commit messages become longer as they have to explain more things, and they also end up explaining the diff so that you can fit more on one page.
I'd suggest getting in the habit of making coherent commits with one change each. Some changes will be trivial, and the diff will be self explanatory. Then you can save your writing effort for commits that are challenging.
On the other hand, if I'm wrong and many changes to have to get bundled, then the commit message would be a good place to explain why.
> Probably most commits should be along the lines of "getting a thing working", not essays about the intricacies of character encoding:
I'm not a fan of that commit as a commit, although it would make a great start for a blog post. The explanation of how the issue was tracked down, is not helpful in understanding what the issue is. On the other hand, while the author describes finding (and replacing) a non-ASCII character masquerading as a space, it would have been more interesting to know what character it was.
I agree that explaining the "why" is useful, but in this case I don't think it deserves much more detail than "ensure the file uses only ASCII characters to avoid a text encoding error while running tests in this specific manner". (I guess I can also see the argument for showing the error message for later searches, too....)
I'd rather have that commit message than one that doesn't explain anything, but it's a bit verbose to my taste because I don't really care how he discovered the issue. I really just need to know what and why.
So let me link to my favorite author of consistently excellent commit messages, Jeff King on the git project itself:
To pick just one, here's a well explained single-line code change. It's subtle, so besides the excellent commit messages, he also adds a comment and a couple tests:
Best of luck! A couple of clarifications as I was writing from the train and didn't do a second draft:
By "backwards" I meant to suggest, have the LLM critique a commit message you wrote. Have it point out vague language, weasel words, generalisation and marketing terms.
The wiki article is good advice for writing in general, not limited to LLMs.
reply