I read on here someone saying to think of a commit message as starting with “When applied, this commit will…” and that helped me a lot coming up with good messages.
Needing a LLM to figure out what your staged work is doing is a real red flag.
Needing a LLM to figure out what your staged work is doing is a real red flag.
> Describe your changes in imperative mood, e.g. "make xyzzy do frotz" instead of "[This patch] makes xyzzy do frotz" or "[I] changed xyzzy to do frotz", as if you are giving orders to the codebase to change its behavior.
• GOOD: “Fix app sending unnecessary requests"
• BAD: “Fixes app sending unnecessary requests”
> Another best practice to help you write good Git commit messages is to use imperative verb form. Using imperative verb form ensures that potential verbs used in your commit messages, like “fixed” or “updated” are written in the correct tense to “fix” and “updated”.
I insist on present tense, imperative mood in every codebase I work on. The Git log makes a whole lot more sense when it can be read this way.
https://git-scm.com/docs/SubmittingPatches#describe-changes
To be clear, the document does lead with:
> Please note that this information is only relevant to you if you plan on contributing to the Git project itself. It is in no shape or form required reading for regular Git users.
In spite of that qualifier, I think that the directions offered do apply extremely well as general guide, too.
> Your code may be clearly written with in-code comment to sufficiently explain how it works with the surrounding code, but those who need to fix or enhance your code in the future will need to know why your code does what it does. [...] You do not have to say "Currently"---the status quo in the problem statement is about the code without your change ...
I like to imagine myself writing an email to one of my colleagues about why we should be doing this change. I do not assume prior knowledge of my intention, but do assume contextual knowledge about the system.