- When something goes wrong, other developers will utilize git blame and then should be able to understand what code was changed, why it was changed, what subset of end-users are affected by the problem, etc. (see below)
Commit messages are attached and distributed with the code
When we change platforms for ticketing, all the context of the issues, features, or tasks will be lost that were once contained in the system. However, with that being said, if that logic and thought process is in the commit message, a new developer (or even senior) can run git blame or git log to understand what was changed (code, logic, etc), why (business logic, code standards, bug, etc.), and how it affects the platform and the company as a whole.
As stated above, your colleagues may read your commit messages to understand your changes.
Now, a long commit message doesn't fully replace code comments, unit tests, end-user documentation, and discussions in PR's and JIRA tickets, but it is the quickest way to learn due to distribution.
Git commit message audience
You are really not writing for yourself. I will repeat that:
You are not writing for yourself.
You know why this what changed and what its purpose is - Junior developers/new hires will not. The way you write your message block should be appropriate for communication to a new hire or a junior member.
- Use technical jargon and assume some familiarity with the purpose and general architecture of the app, but only to the extent that a new hire will understand it.
- AVOID acronyms and abbreviations
- The abbreviations and acronyms are common knowledge to current team members and yourself, but if this is not well documented terminology then it will look like a foreign language to them.
Your messaging should be future proof.
Let’s be honest - You most likely will not be at your current company forever (as much as we would like that), so your knowledge of the codebase leaves with you. So, leaving:
fixed bug in login manager
as your commit without any details, will not serve newcomers down the road as to
- what the bug was
- why it was caused
- who it affected
- how long it’s been an issue
What’s in a git commit?
fix(grid/pinterest): reset left button when returning back to grid from calendar Our Calendar tab utilizes the left (up) navigation as its entry point to Calendar Settings,while Grid, for Instagram, uses it as its entry point to the Stories Grid, where the swap backis handled appropriately. However, for Pinterest, the left/up toolbar navigation isn't needed/required so the automatic reset/handling isn't present which caused the Calendar Settings "gear" to remain present. APPS-1872
[title] empty line [message block]
Let’s break these down a little bit:
- Usually the most difficult to write
- Should be very succinct to what the changes are, as this may be what others will read.
- Be between 50-72 characters in length
- Be able to be used to complete this sentence: “After this commit, ….”
A Blank Line
Read more here : https://chris.beams.io/posts/git-commit/#separate
The message block
- Utilize Markdown to format the text.
- Use bullets when you need to explain a long list
- The message should be clear and understandable on its own without the title
Perspectives to consider when writing the message
The End User
- What problem is being solved?
- If this commit fixes a bug, write how the bug was discovered.
- If we are adding a new feature, explain what sort of end user is going to benefit and why.
- What was the mistake in the existing logic?
- Why was it solved this way? What other ways did you consider but reject?
- Explain the architecture change (if any).
- What risks are associated with this change(s)?
- Does it impact another area?
- Are these changes backwards compatible?
- Is there any TODOs to point out?
- If this commit is fixing a bug, find the commit that caused it and reference it, explaining it's impact.
- What commit caused it? Add the SHA1
- If it was a result of another repo or service provide an external link for reference.
- Mention any JIRA tickets and external discussions related to this.
- See APPS-1234
- Fixes APPS-1236
- Longer discussion here: https://some.link.com/to/your/context
Additional context and conventions
We utilize conventional commits. This adds additional meaning and context to each of our commits, in a human and machine readable syntax. This also provides an easy set of rules for creating an explicit commit history, which opens up automated tools to more easily parse it for things like changelogs.
Commit messages should be able to answer to provide context of the what and the why, as a way to inform colleagues and future developers of the change so the knowledge transfer isn't lost when you leave.
Annotate, document, reference, and explain.