blob: 9213fe5617afbd61eb9b17a30147262a6ed8eff0 [file] [log] [blame]
Chris Kay1b706e62021-11-15 10:50:30 +00001Commit 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
39The following example commit message demonstrates the use of the
40``refactor`` type and the ``amu`` scope:
41
42.. code::
43
44 refactor(amu): factor out register accesses
45
46 This change introduces a small set of register getters and setters to
47 avoid having to repeatedly mask and shift in complex code.
48
49 Change-Id: Ia372f60c5efb924cd6eeceb75112e635ad13d942
50 Signed-off-by: Chris Kay <chris.kay@arm.com>
51
52The following `types` are permissible and are strictly enforced:
53
54+--------------+---------------------------------------------------------------+
55| Scope | Description |
56+==============+===============================================================+
57| ``feat`` | A new feature |
58+--------------+---------------------------------------------------------------+
59| ``fix`` | A bug fix |
60+--------------+---------------------------------------------------------------+
61| ``build`` | Changes that affect the build system or external dependencies |
62+--------------+---------------------------------------------------------------+
63| ``ci`` | Changes to our CI configuration files and scripts |
64+--------------+---------------------------------------------------------------+
65| ``docs`` | Documentation-only changes |
66+--------------+---------------------------------------------------------------+
67| ``perf`` | A code change that improves performance |
68+--------------+---------------------------------------------------------------+
69| ``refactor`` | A code change that neither fixes a bug nor adds a feature |
70+--------------+---------------------------------------------------------------+
71| ``revert`` | Changes that revert a previous change |
72+--------------+---------------------------------------------------------------+
73| ``style`` | Changes that do not affect the meaning of the code |
74| | (white-space, formatting, missing semi-colons, etc.) |
75+--------------+---------------------------------------------------------------+
76| ``test`` | Adding missing tests or correcting existing tests |
77+--------------+---------------------------------------------------------------+
78| ``chore`` | Any other change |
79+--------------+---------------------------------------------------------------+
80
81The permissible `scopes` are more flexible, and we maintain a list of them in
Chris Kay82117d72021-12-01 16:34:55 +000082our :download:`changelog configuration file <../../changelog.yaml>`. Scopes in
83this file are organized by their changelog section, where each changelog section
84has a single scope that is considered to be blessed, and possibly several
85deprecated scopes. Please avoid using deprecated scopes.
Chris Kay1b706e62021-11-15 10:50:30 +000086
87While we don't enforce scopes strictly, we do ask that commits use these if they
88can, or add their own if no appropriate one exists (see :ref:`Adding Scopes`).
89
90It's highly recommended that you use the tooling installed by the optional steps
91in the :ref:`prerequisites <Prerequisites>` guide to validate commit messages
92locally, as commitlint reports a live list of the acceptable scopes.
93
94.. _Adding Scopes:
95
96Adding Scopes
97-------------
98
Chris Kaye326ccd2022-10-10 16:50:14 +010099Scopes that are not present in the changelog configuration file are considered
100to be deprecated, and should be avoided. If you are adding a new component that
101does not yet have a designated scope, please add one.
Chris Kay1b706e62021-11-15 10:50:30 +0000102
103For example, if you are adding or making modifications to `Foo`'s latest and
Chris Kaye326ccd2022-10-10 16:50:14 +0100104greatest new platform `Bar` then you would add it to the `Platforms` changelog
105sub-section, and the hierarchy should look something like this:
Chris Kay1b706e62021-11-15 10:50:30 +0000106
Chris Kaye326ccd2022-10-10 16:50:14 +0100107.. code:: yaml
108
109 - title: Platforms
110
111 subsections:
112 - title: Foo
113 scope: foo
Chris Kay1b706e62021-11-15 10:50:30 +0000114
Chris Kaye326ccd2022-10-10 16:50:14 +0100115 subsections:
116 - title: Bar
117 scope: bar
Chris Kay1b706e62021-11-15 10:50:30 +0000118
119When creating new scopes, try to keep them short and succinct, and use kebab
120case (``this-is-kebab-case``). Components with a product name (i.e. most
121platforms and some drivers) should use that name (e.g. ``gic600ae``,
122``flexspi``, ``stpmic1``), otherwise use a name that uniquely represents the
123component (e.g. ``marvell-comphy-3700``, ``rcar3-drivers``, ``a3720-uart``).
124
125Mandated Trailers
126-----------------
127
128Commits are expected to be signed off with the ``Signed-off-by:`` trailer using
129your real name and email address. You can do this automatically by committing
130with Git's ``-s`` flag.
131
132There may be multiple ``Signed-off-by:`` lines depending on the history of the
133patch, but one **must** be the committer. More details may be found in the
134`Gerrit Signed-off-by Lines guidelines`_.
135
136Ensure that each commit also has a unique ``Change-Id:`` line. If you have
137followed optional steps in the prerequisites to either install the Node.js tools
138or clone the repository using the "`Clone with commit-msg hook`" clone method,
139then this should be done automatically for you.
140
141More details may be found in the `Gerrit Change-Ids documentation`_.
142
143--------------
144
145*Copyright (c) 2021, Arm Limited and Contributors. All rights reserved.*
146
147.. _Conventional Commits: https://www.conventionalcommits.org/en/v1.0.0
148.. _Gerrit Change-Ids documentation: https://review.trustedfirmware.org/Documentation/user-changeid.html
149.. _Gerrit Signed-off-by Lines guidelines: https://review.trustedfirmware.org/Documentation/user-signedoffby.html
150.. _issue: https://developer.trustedfirmware.org/project/board/1/
151.. _quick summary: https://www.conventionalcommits.org/en/v1.0.0/#summary