1Commit Style 2============ 3 4When writing commit messages, please think carefully about the purpose and scope 5of the change you are making: describe briefly what the change does, and 6describe in detail why it does it. This helps to ensure that changes to the 7code-base are transparent and approachable to reviewers, and it allows us to 8keep a more accurate changelog. You may use Markdown in commit messages. 9 10A good commit message provides all the background information needed for 11reviewers to understand the intent and rationale of the patch. This information 12is also useful for future reference. 13 14For example: 15 16- What does the patch do? 17- What motivated it? 18- What impact does it have? 19- How was it tested? 20- Have alternatives been considered? Why did you choose this approach over 21 another one? 22- If it fixes an `issue`_, include a reference. 23 24|TF-A| follows the `Conventional Commits`_ specification. All commits to the 25main repository are expected to adhere to these guidelines, so it is 26**strongly** recommended that you read at least the `quick summary`_ of the 27specification. 28 29To briefly summarize, commit messages are expected to be of the form: 30 31.. code:: 32 33 <type>[optional scope]: <description> 34 35 [optional body] 36 37 [optional footer(s)] 38 39Note that the type, the scope and the first letter of the description (also 40called subject by the commitlint checker) must be lower case. 41 42The following example commit message demonstrates the use of the 43``refactor`` type and the ``amu`` scope: 44 45.. code:: 46 47 refactor(amu): factor out register accesses 48 49 This change introduces a small set of register getters and setters to 50 avoid having to repeatedly mask and shift in complex code. 51 52 Change-Id: Ia372f60c5efb924cd6eeceb75112e635ad13d942 53 Signed-off-by: Chris Kay <chris.kay@arm.com> 54 55The following `types` are permissible and are strictly enforced: 56 57+--------------+---------------------------------------------------------------+ 58| Scope | Description | 59+==============+===============================================================+ 60| ``feat`` | A new feature | 61+--------------+---------------------------------------------------------------+ 62| ``fix`` | A bug fix | 63+--------------+---------------------------------------------------------------+ 64| ``build`` | Changes that affect the build system or external dependencies | 65+--------------+---------------------------------------------------------------+ 66| ``ci`` | Changes to our CI configuration files and scripts | 67+--------------+---------------------------------------------------------------+ 68| ``docs`` | Documentation-only changes | 69+--------------+---------------------------------------------------------------+ 70| ``perf`` | A code change that improves performance | 71+--------------+---------------------------------------------------------------+ 72| ``refactor`` | A code change that neither fixes a bug nor adds a feature | 73+--------------+---------------------------------------------------------------+ 74| ``revert`` | Changes that revert a previous change | 75+--------------+---------------------------------------------------------------+ 76| ``style`` | Changes that do not affect the meaning of the code | 77| | (white-space, formatting, missing semi-colons, etc.) | 78+--------------+---------------------------------------------------------------+ 79| ``test`` | Adding missing tests or correcting existing tests | 80+--------------+---------------------------------------------------------------+ 81| ``chore`` | Any other change | 82+--------------+---------------------------------------------------------------+ 83 84The permissible `scopes` are more flexible, and we maintain a list of them in 85our :download:`changelog configuration file <../../changelog.yaml>`. Scopes in 86this file are organized by their changelog section, where each changelog section 87has a single scope that is considered to be blessed, and possibly several 88deprecated scopes. Please avoid using deprecated scopes. 89 90While we don't enforce scopes strictly, we do ask that commits use these if they 91can, or add their own if no appropriate one exists (see :ref:`Adding Scopes`). 92 93It's highly recommended that you use the tooling installed by the optional steps 94in the :ref:`prerequisites <Prerequisites>` guide to validate commit messages 95locally, as commitlint reports a live list of the acceptable scopes. 96 97.. _Adding Scopes: 98 99Adding Scopes 100------------- 101 102Scopes that are not present in the changelog configuration file are considered 103to be deprecated, and should be avoided. If you are adding a new component that 104does not yet have a designated scope, please add one. 105 106For example, if you are adding or making modifications to `Foo`'s latest and 107greatest new platform `Bar` then you would add it to the `Platforms` changelog 108sub-section, and the hierarchy should look something like this: 109 110.. code:: yaml 111 112 - title: Platforms 113 114 subsections: 115 - title: Foo 116 scope: foo 117 118 subsections: 119 - title: Bar 120 scope: bar 121 122When creating new scopes, try to keep them short and succinct, and use kebab 123case (``this-is-kebab-case``). Components with a product name (i.e. most 124platforms and some drivers) should use that name (e.g. ``gic600ae``, 125``flexspi``, ``stpmic1``), otherwise use a name that uniquely represents the 126component (e.g. ``marvell-comphy-3700``, ``rcar3-drivers``, ``a3720-uart``). 127 128Mandated Trailers 129----------------- 130 131Commits are expected to be signed off with the ``Signed-off-by:`` trailer using 132your real name and email address. You can do this automatically by committing 133with Git's ``-s`` flag. By adding this line the contributor certifies the 134contribution is made under the terms of the :download:`Developer Certificate of 135Origin <../../dco.txt>`. 136 137There may be multiple ``Signed-off-by:`` lines depending on the history of the 138patch, but one **must** be the committer. More details may be found in the 139`Gerrit Signed-off-by Lines guidelines`_. 140 141Ensure that each commit also has a unique ``Change-Id:`` line. If you have 142followed optional steps in the prerequisites to either install the Node.js tools 143or clone the repository using the "`Clone with commit-msg hook`" clone method, 144then this should be done automatically for you. 145 146More details may be found in the `Gerrit Change-Ids documentation`_. 147 148-------------- 149 150*Copyright (c) 2021-2025, Arm Limited and Contributors. All rights reserved.* 151 152.. _Conventional Commits: https://www.conventionalcommits.org/en/v1.0.0 153.. _Gerrit Change-Ids documentation: https://review.trustedfirmware.org/Documentation/user-changeid.html 154.. _Gerrit Signed-off-by Lines guidelines: https://review.trustedfirmware.org/Documentation/user-signedoffby.html 155.. _issue: https://github.com/TrustedFirmware-A/trusted-firmware-a/issues 156.. _quick summary: https://www.conventionalcommits.org/en/v1.0.0/#summary 157