Writing commit messages

🌈 Abstract

This is a guide on writing good commit messages for version control systems like Git. The author discusses the importance of including the right information in commit messages, such as the purpose of the change, the reasoning behind it, and how it affects the codebase. The guide also covers formatting and style considerations, as well as the differences between temporary and permanent commit messages.

🙋 Q&A

[01] Importance of Commit Messages

1. What are the key reasons the author believes commit messages are important?

• Commit messages provide valuable information to various readers, such as developers trying to understand the history and reasoning behind changes, or users wanting to know what bug was fixed or feature was added.
• Commit messages can serve as documentation, explaining changes to APIs or data formats that other developers need to know about.
• Well-written commit messages can make it easier to navigate the codebase history and understand the evolution of the project.

2. What are some common mistakes the author has observed in commit messages?

• Focusing too much on minor stylistic details (e.g. capitalization, punctuation) rather than the substance of the changes.
• Burying the most important information (e.g. description of the bug fix or feature addition) deep within a long, rambling message.
• Failing to clearly indicate whether a description is referring to the old or new state of the code.

3. How does the author recommend structuring commit messages to improve readability and convey the right information?

• Use a "pyramid" structure, with the most important information at the top and additional context or background details further down.
• Clearly distinguish between descriptions of the old and new states of the code (e.g. using "Before this change..." and "Now...").
• Consider breaking up large changes into a series of smaller, more focused commits with appropriate explanations.

[02] Commit Message Content

1. What are the key pieces of information the author recommends including in a commit message?

• A summary of the change, including any user-visible behavior changes or bug fixes.
• An explanation of the reasoning behind the change and why it is desirable.
• Details on how the change was implemented, such as changes to APIs or data formats.
• Links to any related external context, such as bug reports or feature requests.
• A description of the overall structure or interesting parts of the change, if the patch is large.

2. When should some of this information be included in the commit message versus elsewhere?

• If submitting a patch to someone else's project, include the justification for accepting the patch in the commit message, rather than just in a separate cover letter.
• For changes to APIs or data formats, summarize the changes in the commit message, but provide full documentation in the codebase itself.
• Consider breaking up large changes into a series of smaller, more focused commits to reduce the need for extensive explanations.

[03] Formatting and Style

1. What formatting guidelines does the author recommend for commit messages?

• Use physical newlines to wrap paragraphs to a reasonable width, rather than relying on the display tool to wrap the text.
• Use Markdown sparingly, and ensure the message is still readable as plain text without rendering the Markdown.
• Follow any local conventions, such as using a subject line format expected by Git tooling.

2. How does the author recommend handling temporary or work-in-progress commit messages?

• For initial development, focus on getting the code working first, and use more terse "note to self" style commit messages.
• Once the work is complete, rearrange the commits and rewrite the messages to be more informative for others.
• Temporary commit messages can be more informal and focused on your own needs, while permanent messages should be written with a wider audience in mind.