1.. SPDX-License-Identifier: BSD-3-Clause
2.. SPDX-FileCopyrightText: Copyright TF-RMM Contributors.
3
4Commit Style
5============
6
7When writing commit messages, please think carefully about the purpose and scope
8of the change you are making: describe briefly what the change does, and
9describe in detail why it does it. This helps to ensure that changes to the
10code-base are transparent and approachable to reviewers, and it allows us to
11keep a more accurate changelog. You may use Markdown in commit messages.
12
13A good commit message provides all the background information needed for
14reviewers to understand the intent and rationale of the patch. This information
15is also useful for future reference. For example:
16
17- What does the patch do?
18- What motivated it?
19- What impact does it have?
20- How was it tested?
21- Have alternatives been considered? Why did you choose this approach over
22  another one?
23- If it fixes an `issue`_, include a reference.
24
25    - Github prescribes a format for issue fixes that can be used within the
26      commit message:
27
28      .. code::
29
30          Fixes TF-RMM/tf-rmm#<issue-number>
31
32Commit messages are expected to be of the following form, based on conventional
33commits:
34
35.. code::
36
37    <type>[optional scope]: <description>
38
39    [optional body]
40
41    [optional trailer(s)]
42
43The following `types` are permissible :
44
45+--------------+---------------------------------------------------------------+
46| Type         | Description                                                   |
47+==============+===============================================================+
48| ``feat``     | A new feature                                                 |
49+--------------+---------------------------------------------------------------+
50| ``fix``      | A bug fix                                                     |
51+--------------+---------------------------------------------------------------+
52| ``build``    | Changes that affect the build system or external dependencies |
53+--------------+---------------------------------------------------------------+
54| ``docs``     | Documentation-only changes                                    |
55+--------------+---------------------------------------------------------------+
56| ``perf``     | A code change that improves performance                       |
57+--------------+---------------------------------------------------------------+
58| ``refactor`` | A code change that neither fixes a bug nor adds a feature     |
59+--------------+---------------------------------------------------------------+
60| ``revert``   | Changes that revert a previous change                         |
61+--------------+---------------------------------------------------------------+
62| ``style``    | Changes that do not affect the meaning of the code            |
63|              | (white-space, formatting, missing semi-colons, etc.)          |
64+--------------+---------------------------------------------------------------+
65| ``test``     | Adding missing tests or correcting existing tests             |
66+--------------+---------------------------------------------------------------+
67| ``chore``    | Any other change                                              |
68+--------------+---------------------------------------------------------------+
69
70The permissible `scopes` are more flexible, and we recommend that they match
71the directory where the patch applies (or where the main subject of the
72patch is, in case of changes accross several directories).
73
74The following example commit message demonstrates the use of the
75``refactor`` type and the ``lib/arch`` scope:
76
77.. code::
78
79    refactor(lib/arch): ...
80
81    This change introduces ....
82
83    Change-Id: ...
84    Signed-off-by: ...
85
86In addition, the width of the commit message must be no more than 72 characters.
87
88.. _mandated-trailers:
89
90Mandated Trailers
91-----------------
92
93Commits are expected to be signed off with the ``Signed-off-by:`` trailer using
94your real name and email address. You can do this automatically by committing
95with Git's ``-s`` flag.
96
97There may be multiple ``Signed-off-by:`` lines depending on the history of the
98patch. See :ref:`copyright-license-guidance` for guidance on this.
99
100Ensure that each commit also has a unique ``Change-Id:`` line. If you have
101cloned the repository using the "`Clone with commit-msg hook`" clone method,
102then this should be done automatically for you.
103
104More details may be found in the `Gerrit Change-Ids documentation`_.
105
106--------------
107
108.. _Gerrit Change-Ids documentation: https://review.trustedfirmware.org/Documentation/user-changeid.html
109.. _issue: https://github.com/TF-RMM/tf-rmm/issues
110