1Commits 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 details why it does it. This helps to ensure that changes to the
7code-base are transparent and approachable to reviewers, and it allows maintainers
8to keep 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, detail what the issue is and provide any pointers/resources
23  that are found necessary.
24
25Hafnium follows the `Conventional Commits`_ specification. All commits to the
26main repository and its submodules are expected to adhere to these guidelines,
27so it is **strongly** recommended that you read at least the `quick summary`_
28of the specification.
29
30To briefly summarize, commit messages are expected to be of the form:
31
32.. code::
33
34    <type>[optional scope]: <description>
35
36    [optional body]
37
38    [optional footer(s)]
39
40    Signed-off-by: Contributor <contributor@email.com>
41    Change-Id: 00000000000000000000000000000000000000000
42
43The maximum character counts per line are:
44
45* 50 for the commit title.
46* 72 for the commit body.
47
48The following `types` are permissible and are strictly enforced:
49
50+--------------+---------------------------------------------------------------+
51| Type         | Description                                                   |
52+==============+===============================================================+
53| ``feat``     | A new feature                                                 |
54+--------------+---------------------------------------------------------------+
55| ``fix``      | A bug fix                                                     |
56+--------------+---------------------------------------------------------------+
57| ``build``    | Changes that affect the build system or external dependencies |
58+--------------+---------------------------------------------------------------+
59| ``ci``       | Changes to CI configuration files and scripts                 |
60+--------------+---------------------------------------------------------------+
61| ``docs``     | Documentation-only changes                                    |
62+--------------+---------------------------------------------------------------+
63| ``perf``     | A code change that improves performance                       |
64+--------------+---------------------------------------------------------------+
65| ``refactor`` | A code change that neither fixes a bug nor adds a feature     |
66+--------------+---------------------------------------------------------------+
67| ``revert``   | Changes that revert a previous change                         |
68+--------------+---------------------------------------------------------------+
69| ``style``    | Changes that do not affect the meaning of the code            |
70|              | (white-space, formatting, missing semi-colons, etc.)          |
71+--------------+---------------------------------------------------------------+
72| ``test``     | Adding missing tests or correcting existing tests             |
73+--------------+---------------------------------------------------------------+
74| ``chore``    | Any other change                                              |
75+--------------+---------------------------------------------------------------+
76
77While we don't enforce scopes strictly, we do ask that commits use these if they
78can. These should reference the functionality the patch relates to.
79
80Mandated Trailers
81-----------------
82
83Commits are expected to be signed off with the ``Signed-off-by:`` trailer using
84your real name and email address. You can do this automatically by committing
85with Git's ``-s`` flag.
86
87There may be multiple ``Signed-off-by:`` lines depending on the history of the
88patch, but one **must** be the committer. More details may be found in the
89`Gerrit Signed-off-by Lines guidelines`_.
90
91Ensure that each commit also has a unique ``Change-Id:`` line.
92
93If you have followed optional steps in the prerequisites to install the clone the
94repository using the "`Clone with commit-msg hook`" clone method, then this should
95be done automatically for you.
96
97More details may be found in the `Gerrit Change-Ids documentation`_.
98
99.. _Conventional Commits: https://www.conventionalcommits.org/en/v1.0.0
100.. _Gerrit Change-Ids documentation: https://review.trustedfirmware.org/Documentation/user-changeid.html
101.. _Gerrit Signed-off-by Lines guidelines: https://review.trustedfirmware.org/Documentation/user-signedoffby.html
102.. _quick summary: https://www.conventionalcommits.org/en/v1.0.0/#summary
103
104Commit Linting
105--------------
106
107`Commitlint`_ helps enforce the conventional commits specification by
108providing commit message linting capabilities.
109
110Navigate to the Hafnium root directory. Node Version Manager (nvm) is
111required to install the Node.js dependency for Commitlint. To install
112nvm run the following command:
113
114.. code:: shell
115
116  wget -qO- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.1/install.sh | bash
117
118To install Node.js, first reload the shell configuration to ensure that nvm is
119available.
120
121.. code:: shell
122
123  source ~/.bashrc
124
125Run the following command to install Node.js:
126
127.. code:: shell
128
129  nvm install 20
130
131To test that commit linting is working, navigate to the Hafnium root
132directory and run the following:
133
134.. code:: shell
135
136  make commitlint
137
138By default this will apply linting to the most recent commit message.
139
140Additionally, you can lint any range of commit messages by setting the ``COMMITLINT_FROM`` and ``COMMITLINT_TO`` arguments.
141An example of this is as follows:
142
143.. code:: shell
144
145  make commitlint COMMITLINT_FROM=HEAD~3 COMMITLINT_TO=HEAD
146
147.. _Commitlint: https://commitlint.js.org
148--------------
149
150*Copyright (c) 2023, Arm Limited and Contributors. All rights reserved.*
151