At Coderus, we have recently been considering how we approach commit messages and their role in providing documentation for a project. We previously provided some loose standards on how these messages should look – it would need to include a type, a scope if appropriate and a short message explaining the change. However, we found that while better than having no standards, the intended purpose of including commit messages was often overlooked with the content being overly generic or too brief.
We want commit messages to be a useful medium for knowledge sharing, where the intention or motivation of the author can be presented with their implementations and fixes while remaining useful when viewed as part of a commit log. To encourage this we have redesigned our internal commit guidelines to promote standardised contributions which aim to ensure proper description and contextualisation of changes with in-depth explanations of the reasons why the change was required, thought process behind the new code and discussion of alternative approaches considered.
How This Works
In practice, this means the first line of the commit needs to include a type, a scope and a short summary of the change all within 72 characters; we want this line to be concise but relevant. When this commit summary is viewed in a list with other summaries, such the output of a git log –oneline, each line (with the 7 characters short commit hash and space prefix) needs to fit without wrapping within an 80 character limit – historically the character width of terminals and a commonly used line length limit.
If additional information is required the message body can be added which should include the reason the change was needed, the intention behind the solution and if necessary, why the solution was chosen over the alternatives. The line length for the body is relaxed to 100 characters – we find these are typically read within IDEs or Code Reviews rather than terminals, so the stricter limit isn’t necessary.
Encouraging new standards can be a slow process, which is why we have introduced a “Commit of the week” award, where any developer can nominate a commit to a pool to be voted on each week. The winner receives the admiration of their colleagues but more importantly something from Tesco’s cakes aisle.
