3.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.
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.
TF-A follows the Conventional Commits specification. All commits to the main repository are expected to adhere to these guidelines, so it is strongly recommended that you read at least the quick summary of the specification.
To briefly summarize, commit messages are expected to be of the form:
<type>[optional scope]: <description>
The following example commit message demonstrates the use of the
refactor type and the
refactor(amu): factor out register accesses
This change introduces a small set of register getters and setters to
avoid having to repeatedly mask and shift in complex code.
Signed-off-by: Chris Kay <firstname.lastname@example.org>
The following types are permissible and are strictly enforced:
A new feature
A bug fix
Changes that affect the build system or external dependencies
Changes to our CI configuration files and scripts
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 maintain a list of them in
changelog configuration file. Scopes in
this file are organized by their changelog section, where each changelog section
has a single scope that is considered to be blessed, and possibly several
deprecated scopes. Please avoid using deprecated scopes.
While we don’t enforce scopes strictly, we do ask that commits use these if they can, or add their own if no appropriate one exists (see Adding Scopes).
It’s highly recommended that you use the tooling installed by the optional steps in the prerequisites guide to validate commit messages locally, as commitlint reports a live list of the acceptable scopes.
3.3.1. Adding Scopes
Scopes that are not present in the changelog configuration file are considered to be deprecated, and should be avoided. If you are adding a new component that does not yet have a designated scope, please add one.
For example, if you are adding or making modifications to Foo’s latest and greatest new platform Bar then you would add it to the Platforms changelog sub-section, and the hierarchy should look something like this:
- title: Platforms
- title: Foo
- title: Bar
When creating new scopes, try to keep them short and succinct, and use kebab
this-is-kebab-case). Components with a product name (i.e. most
platforms and some drivers) should use that name (e.g.
stpmic1), otherwise use a name that uniquely represents the
3.3.2. 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
-s flag. By adding this line the contributor certifies the
contribution is made under the terms of the
Developer Certificate of
There may be multiple
Signed-off-by: lines depending on the history of the
patch, but one must be the committer. More details may be found in the
Gerrit Signed-off-by Lines guidelines.
Ensure that each commit also has a unique
Change-Id: line. If you have
followed optional steps in the prerequisites to either install the Node.js tools
or clone 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.
Copyright (c) 2021, Arm Limited and Contributors. All rights reserved.