Capitalized, short (<=50 chars) summary without dot
Description. More detailed explanatory text, if necessary. Wrap it to about 72 characters or so. In some contexts, the first line is treated as the subject of an email and the rest of the text as the body. The blank line separating the summary from the body is critical (unless you omit the body entirely); tools like rebase can get confused if you run the two together.
Write your commit message in the imperative: "Fix bug" and not "Fixed bug" or "Fixes bug." This convention matches up with commit messages generated by commands like git merge and git revert.
Further paragraphs come after blank lines.
-
Bullet points are okay, too
-
Typically a hyphen or asterisk is used for the bullet, followed by a single space, with blank lines in between, but conventions vary here
-
Use a hanging indent
Good commit messages serve at least three important purposes:
-
To speed up the reviewing process.
-
To help us write a good release note.
-
To help the future maintainers, say five years into the future, to find out why a particular change was made to the code or why a specific feature was added.
This question tells reviewers of your pull request what to expect in the commit, allowing them to more easily identify and point out unrelated changes. It may fix a bug, it may add a feature, it may improve performance, reliability, stability, or just be a change for the sake of correctness.
Describe, at a high level, what was done to affect change. If your change is obvious, you may be able to omit addressing this question.
This is the most important question to answer, as it can point out problems where you are making too many changes in one commit or branch. One or two bullet points for related changes may be okay, but five or six are likely indicators of a commit that is doing too many things.
-
If a change is found to be flawed later, it may be necessary to revert the broken commit. This is much easier to do if there are not other unrelated code changes entangled with the original commit.
-
Do not mix two unrelated functional changes. The reviewer will find it harder to identify flaws if two unrelated changes are mixed together. If it becomes necessary to later revert a broken commit, the two unrelated changes will need to be untangled, with further risk of bug creation.
-
Whitespace changes, coding-standards changes, refactoring, typos should be in separated commits. Having all those changes together with code changes may introduce bugs, though because almost no-one will spot the bug hidden in hundreds of lines that got reindented for fun and profit.
-
Do not create a single giant commit with one feature. It may well be the case that the code for a new feature is only useful when all of it is present. This does not, however, imply that the entire feature should be provided in a single commit. New features often entail refactoring existing code. It is highly desirable that any refactoring is done in commits which are separate from those implementing the new feature. This helps reviewers and test suites validate that the refactoring has no unintentional functional changes. Even the newly written code can often be split up into multiple pieces that can be independently reviewed. For example, changes which add new internal APIs/classes, can be in self-contained commits. Again this leads to easier code review. It also allows other developers to cherry-pick small parts of the work, if the entire new feature is not immediately ready for merge. Addition of new public HTTP APIs or RPC interfaces should be done in commits separate from the actual internal implementation. This will encourage the author & reviewers to think about the generic API/RPC design, and not simply pick a design that is easier for their currently chosen internal implementation.
Verb (Fixes, Closes, Related) and ticket number, if it’s applicable