Writing commit messages
a day ago
- Focus on conveying important information and reasoning, not typography or grammar.
- Explain what and why a change was made, not just how it was implemented.
- Consider the diverse readers: those using git bisect, git blame, code reviewers, and future maintainers.
- Use pyramid writing style: put the most important information first for quick skimming.
- Include a Git-style subject line that provides a brief summary, followed by a blank line and detailed body.
- Write plain text, wrap paragraphs at reasonable widths, and avoid Markdown that breaks plain-text readability.
- Break large patches into smaller, logical commits to make changes easier to understand.
- For temporary commits during development, keep messages minimal; rewrite them for permanent history.
- Clearly mark descriptions of old vs. new code to avoid ambiguity.
- Document changes to APIs or behavior concisely, and keep in-code documentation updated.