Section 52.2 Commit Messages
Commit messages are a critical tool when locating and reviewing changes to the project. In a way, they are like an index of a book. We take great care to have useful and concise commit messages, and to this end, we are likely to edit yours. But you can help by doing some simple things, so we do not have to.
- Begin with a capital letter.
- Do not end with a period.
- Do not repeat information available by examining the commit itself. Bad: “Changes in foo.xsl”
- No longer than roughly 60 to 70 characters, and never onto multiple lines.
- You can find lots of advice about phrasing commit messages with action words, or in ways that describe how the code will be different. These make for good reading, but we do not adhere slavishly to any one formulation.
- For whatever reason, we isolate and prefix messages with the name of a relevant conversion such as “HTML: ”, or other areas, such as “Guide: ” or “Schema: ”. Scroll the list of commit messages to see the range.
- For pull requests we will append “ (PR #nnnn)”. (This provides a permanent record somewhat independent of GitHub, and GitHub will utilize this number.)
