docs: summarize changes in title, but be specific More detailed explanatory text, if necessary. The blank line
separating the summary from the body is critical; various tools
like `log`, `shortlog` and `rebase` can get confused if you run
the two together. Wrap the body to a fixed width consistent with the rest of the git history.
Explain how the code was, before your change. Explain the problem that this commit is solving.
Explain why the problem is important to solve.
Explain (briefly) what the new situation looks like. No need
to explain the mechanism in detail: the code and comments
should explain that already.
Are there side effects or other unintuitive consequences of this change? Here's the place to explain them. Further paragraphs come after blank lines. - Bullet points are okay, too - Typically a hyphen or asterisk is used for the bullet, preceded by a single space, with blank lines in between, but conventions vary here
Prefer imperative voice for the subject, and declarative
(descriptive) voice for the body and release note.
If Ifthere youare userelated anissues, issuemention tracker,them putin referencesthe tocommit themmessage: at the bottom ofResolves: #123
(this auto-closes the explanatoryissue text,when likethe this:PR Resolves: #123is merged)
See also: #456, #789
(this just cross-references the PR with the issues) Release note (general change): The release note should outline
what changed, how a user can see what changed, and why it was
important / what the impact is. For bug fixes, it should
also explain the symptoms of the bug pre-fix and which versions
are affected. It should remain concise. A release note can contain multiple paragraphs. This is useful to e.g. provide examples. However it does imply the release note text must appear after the detailed explanation, otherwise the detailed explanation will be considered part of the release note. Release note (general change): if there are multiple release notes, each of them should start with its own "Release note" prefix.
- Learn about how commit messages help the reviewers and future maintainers in our PR organization philosophy.
- Think about the following questions:
- Why should this change should be made? What is wrong with the current code? Explain how things were prior to the patch.
- Why should it be done in this particular way?
- Did you try a different way before? Describe alternate approaches you considered.
- Can a reviewer confirm that it works as intended?
- What are the consequences for further users of this code? Do they need to understand the code in a new way?
- Was this discussed before? Add a link to an existing public issue if it exists, to provide context. (Note that the commit should still be self-explanatory even if there is a linked issue.)
- Avoid URLs in commit messages.
- Use git hashes instead of URLs to refer to other changes.
- If there was external documentation or discussions, also summarize the relevant points.
- Wrap the message body so that lines are less than 100 characters long. There are too many tools that cannot re-flow paragraphs, or do a miserable job at it, to afford using unwrapped paragraphs in commit messages.
- Suggestion: use your editor's standard wrapping width of 72 characters so as to make commit messages uniform across the entire project. Many of your fellow developers also use the default configuration of their editor that will wrap at 72 columns.
- If a URL is too long, give it its own line, but don't break or wrap it.