3.3.Commit Style
When writing commit messages, please think carefully about the purpose and scopeof the change you are making: describe briefly what the change does, anddescribe in detail why it does it. This helps to ensure that changes to thecode-base are transparent and approachable to reviewers, and it allows us tokeep a more accurate changelog. You may use Markdown in commit messages.
A good commit message provides all the background information needed forreviewers to understand the intent and rationale of the patch. This informationis 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 overanother one?
If it fixes anissue, include a reference.
TF-A follows theConventional Commits specification. All commits to themain repository are expected to adhere to these guidelines, so it isstrongly recommended that you read at least thequick summary of thespecification.
To briefly summarize, commit messages are expected to be of the form:
<type>[optionalscope]:<description>[optionalbody][optionalfooter(s)]
Note that the type, the scope and the first letter of the description (alsocalled subject by the commitlint checker) must be lower case.
The following example commit message demonstrates the use of therefactor type and theamu scope:
refactor(amu):factoroutregisteraccessesThischangeintroducesasmallsetofregistergettersandsetterstoavoidhavingtorepeatedlymaskandshiftincomplexcode.Change-Id:Ia372f60c5efb924cd6eeceb75112e635ad13d942Signed-off-by:ChrisKay<chris.kay@arm.com>
The followingtypes are permissible and are strictly enforced:
Scope | Description |
|---|---|
| A new feature |
| A bug fix |
| Changes that affect the build system or external dependencies |
| Changes to our CI configuration files and scripts |
| 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 permissiblescopes are more flexible, and we maintain a list of them inourchangelogconfigurationfile. Scopes inthis file are organized by their changelog section, where each changelog sectionhas a single scope that is considered to be blessed, and possibly severaldeprecated scopes. Please avoid using deprecated scopes.
While we don’t enforce scopes strictly, we do ask that commits use these if theycan, or add their own if no appropriate one exists (seeAdding Scopes).
It’s highly recommended that you use the tooling installed by the optional stepsin theprerequisites guide to validate commit messageslocally, 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 consideredto be deprecated, and should be avoided. If you are adding a new component thatdoes not yet have a designated scope, please add one.
For example, if you are adding or making modifications toFoo’s latest andgreatest new platformBar then you would add it to thePlatforms changelogsub-section, and the hierarchy should look something like this:
-title:Platformssubsections:-title:Fooscope:foosubsections:-title:Barscope:bar
When creating new scopes, try to keep them short and succinct, and use kebabcase (this-is-kebab-case). Components with a product name (i.e. mostplatforms and some drivers) should use that name (e.g.gic600ae,flexspi,stpmic1), otherwise use a name that uniquely represents thecomponent (e.g.marvell-comphy-3700,rcar3-drivers,a3720-uart).
3.3.2.Mandated Trailers
Commits are expected to be signed off with theSigned-off-by: trailer usingyour real name and email address. You can do this automatically by committingwith Git’s-s flag. By adding this line the contributor certifies thecontribution is made under the terms of theDeveloperCertificateofOrigin.
There may be multipleSigned-off-by: lines depending on the history of thepatch, but onemust be the committer. More details may be found in theGerrit Signed-off-by Lines guidelines.
Ensure that each commit also has a uniqueChange-Id: line. If you havefollowed optional steps in the prerequisites to either install the Node.js toolsor 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 theGerrit Change-Ids documentation.
Copyright (c) 2021-2025, Arm Limited and Contributors. All rights reserved.