What is a commit message and why is it important?A commit message is a text description that developers write before submitting code changes to a version control system. Git, the popular version control system that TubeMogul uses, requires any commit to have a message to accept it. These messages provide an easy way for a developer to gather information about a code change without reading the code. Commit messages can also act as context before reading the code. However, if the commit message is not well formed and meaningful, it doesn’t serve much purpose. Well formed commit messages provide useful information for code reviewers, merge masters, quality engineers, future developers, and even executives as part of the release notes.
It’s not hard (at all) to submit code with well-formed commit messages, and the time and effort committed will pay off many times over when it comes to knowledge sharing with others (or when you have to revisit some old code a month later and try to figure out “what the heck was I doing here!?”).
What makes a commit message well formed?There are handful of things that help make a commit message well-formed. First, Git commit message are composed of 2 parts – header and body. At TubeMogul we use JIRA for issue tracking, so we use the header line of a commit message to tell us which JIRA ticket we are committing against, as well as a very short description of the change to commit.
The HeaderHere is a sample header (or summary) line:
If you use the command git log –oneline or git shortlog in your module, you will see the header lines from Git log history, giving a quick overview of the module in chronological order as small changes introduced over time. This is why the header should be precise but meaningful. For example, “Fix bug that…”, “Add file/feature…” or “Increase code coverage for…”, etc.
After you write the header, add a full blank line as a gap before starting the body of the commit message. This works as a visual separator between the two majors parts of a commit message.
The BodyNext, a detailed message about the commit serves as the body of the message. The body of a Git commit message can be as long as you want, but we generally discourage people from authoring novels for commit messages. TubeMogul’s commits wrap every line after 72 characters as a best practice for consistency and to follow standard industry practice.
Good commit message bodies should provide answers to the following 3 questions:
- Why is it necessary? It may fix a bug, add a feature, improve performance, reliability, or stability.
- How does it address the issue? This should be a high-level description of what the approach was.
- What side effect could the commit have? This may include benchmarks, side effects, or features that need focus during testing.
Finally, provide links to any external documents, if needed, as part of the message.
Best practices when creating commit messages.
- Commit frequently during development, then clean up to make a push. If it’s difficult to summarize what your commit does because it includes several logical changes or bug fixes, consider splitting into several commits. Each commit should represent a single change.
- Avoid lazy commit messages. Funny (“Fixes all our problems”) or meaningless (“asdf asdf”) commit messages were once common occurrences at TubeMogul. Take 2 minutes to provide good information with your commit message, and you may save yourself a headache later.
- Keep the audience in mind when writing commit messages. Your commit message will speed up the code review process, help make good release notes, give quality engineers ideas about edge cases to test, and help onboard new developers faster. Don’t describe the code; describe the intent and the approach to the change.
TL;DR. When creating your commit messages, avoid making these common excuses:
- I’m in a hurry. Yes, but it will make referencing the change in the future much easier.
- But it works! It may work now, but code is always changing.
- I am the only one working on it. Not true, any software project is a collaborative project.
- Do people look at Git log history? Yes. You may not, but others will.