These guidelines are based off of this guide. Some of the key takeaways, plus some other opinionated guidelines:
- Clarity is key: a commit should be clear even to a viewer who doesn’t have the full context in which it was made.
- Start your commit message with a verb, and use sentence case capitalization.
- Use the imperative verb when writing a commit message (see the link above if you don’t know what that means). Example: "
Fixed" → "Fix" - Commit things that make sense to be grouped in a single commit. Ask yourself "does it make sense for someone to cherry pick this single commit? Is there something missing in it, or something extra that the person wouldn't need?" - if you do that, you'll end up aiming for 1 commit per fix or feature, which makes the codebase cleaner.
- Test what you are fixing before committing. Only commit what you’ve tested and are sure that is good to go. This avoids unnecessary commits fixing the same single issue.
- If you're using smart commits, don’t commit only the JIRA ticket identifier 😢 The viewer would have to open JIRA to know what that commit was for.
- Avoid commit messages like “WIP”, this is not helpful at all. Wait until you have completed a task worth committing for. It shouldn't take you multiple days to have code worth committing anyway.
- Unpopular opinion: never ever rewrite git history. No exceptions. No force pushes, no remote git squashing (local is fine). IMO git should be treated as a reliable, permanent and immutable stream of data, like a blockchain, and thus should never be modified.
- Lastly, this is not required but try to make your commit messages short (under 70 characters, extra kudos if it's under 50 as recommended by git). This enforces the commit message to be succinct enough, and avoids doing a single commit for multiple completely unrelated issues.
Remember: the ultimate goal is a git history that’s easy to read and completely self-explanatory.