3. Commit Style
When writing commit messages, please think carefully about the purpose and scope of the change you are making: describe briefly what the change does, and describe in detail why it does it. This helps to ensure that changes to the code-base are transparent and approachable to reviewers, and it allows us to keep a more accurate changelog. You may use Markdown in commit messages.
A good commit message provides all the background information needed for reviewers to understand the intent and rationale of the patch. This information is also useful for future reference. For example:
What does the patch do?
What motivated it?
What impact does it have?
How was it tested?
Have alternatives been considered? Why did you choose this approach over another one?
If it fixes an issue, include a reference.
Github prescribes a format for issue fixes that can be used within the commit message:
Fixes TF-RMM/tf-rmm#<issue-number>
Commit messages are expected to be of the following form, based on conventional commits:
<type>[optional scope]: <description>
[optional body]
[optional trailer(s)]
The following types are permissible :
Type |
Description |
---|---|
|
A new feature |
|
A bug fix |
|
Changes that affect the build system or external dependencies |
|
Documentation-only changes |
|
A code change that improves performance |
|
A code change that neither fixes a bug nor adds a feature |
|
Changes that revert a previous change |
|
Changes that do not affect the meaning of the code (white-space, formatting, missing semi-colons, etc.) |
|
Adding missing tests or correcting existing tests |
|
Any other change |
The permissible scopes are more flexible, and we recommend that they match the directory where the patch applies (or where the main subject of the patch is, in case of changes accross several directories).
The following example commit message demonstrates the use of the
refactor
type and the lib/arch
scope:
refactor(lib/arch): ...
This change introduces ....
Change-Id: ...
Signed-off-by: ...
In addition, the width of the commit message must be no more than 72 characters.
3.1. Mandated Trailers
Commits are expected to be signed off with the Signed-off-by:
trailer using
your real name and email address. You can do this automatically by committing
with Git’s -s
flag.
There may be multiple Signed-off-by:
lines depending on the history of the
patch. See License and Copyright for Contributions for guidance on this.
Ensure that each commit also has a unique Change-Id:
line. If you have
cloned the repository using the “Clone with commit-msg hook” clone method,
then this should be done automatically for you.
More details may be found in the Gerrit Change-Ids documentation.