blob: a7f248ff283d897503ed041e12a330c37ab9dd68 [file] [log] [blame]
Commits Style
=============
When writing commit messages, please think carefully about the purpose and scope
of the change you are making: describe briefly what the change does, and
describe in details why it does it. This helps to ensure that changes to the
code-base are transparent and approachable to reviewers, and it allows maintainers
to keep a more accurate changelog. You may use Markdown in commit messages.
A good commit message provides all the background information needed for
reviewers to understand the intent and rationale of the patch. This information
is 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 over
another one?
- If it fixes an issue, detail what the issue is and provide any pointers/resources
that are found necessary.
Hafnium follows the `Conventional Commits`_ specification. All commits to the
main repository and its submodules are expected to adhere to these guidelines,
so it is **strongly** recommended that you read at least the `quick summary`_
of the specification.
To briefly summarize, commit messages are expected to be of the form:
.. code::
<type>[optional scope]: <description>
[optional body]
[optional footer(s)]
Signed-off-by: Contributor <contributor@email.com>
Change-Id: 00000000000000000000000000000000000000000
The maximum character counts per line are:
* 50 for the commit title.
* 72 for the commit body.
The following `types` are permissible and are strictly enforced:
+--------------+---------------------------------------------------------------+
| Type | Description |
+==============+===============================================================+
| ``feat`` | A new feature |
+--------------+---------------------------------------------------------------+
| ``fix`` | A bug fix |
+--------------+---------------------------------------------------------------+
| ``build`` | Changes that affect the build system or external dependencies |
+--------------+---------------------------------------------------------------+
| ``ci`` | Changes to CI configuration files and scripts |
+--------------+---------------------------------------------------------------+
| ``docs`` | Documentation-only changes |
+--------------+---------------------------------------------------------------+
| ``perf`` | A code change that improves performance |
+--------------+---------------------------------------------------------------+
| ``refactor`` | A code change that neither fixes a bug nor adds a feature |
+--------------+---------------------------------------------------------------+
| ``revert`` | Changes that revert a previous change |
+--------------+---------------------------------------------------------------+
| ``style`` | Changes that do not affect the meaning of the code |
| | (white-space, formatting, missing semi-colons, etc.) |
+--------------+---------------------------------------------------------------+
| ``test`` | Adding missing tests or correcting existing tests |
+--------------+---------------------------------------------------------------+
| ``chore`` | Any other change |
+--------------+---------------------------------------------------------------+
While we don't enforce scopes strictly, we do ask that commits use these if they
can. These should reference the functionality the patch relates to.
Mandated Trailers
-----------------
Commits are expected to be signed off with the ``Signed-off-by:`` trailer using
your real name and email address. You can do this automatically by committing
with Git's ``-s`` flag.
There may be multiple ``Signed-off-by:`` lines depending on the history of the
patch, but one **must** be the committer. More details may be found in the
`Gerrit Signed-off-by Lines guidelines`_.
Ensure that each commit also has a unique ``Change-Id:`` line.
If you have followed optional steps in the prerequisites to install the 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 the `Gerrit Change-Ids documentation`_.
.. _Conventional Commits: https://www.conventionalcommits.org/en/v1.0.0
.. _Gerrit Change-Ids documentation: https://review.trustedfirmware.org/Documentation/user-changeid.html
.. _Gerrit Signed-off-by Lines guidelines: https://review.trustedfirmware.org/Documentation/user-signedoffby.html
.. _quick summary: https://www.conventionalcommits.org/en/v1.0.0/#summary
--------------
*Copyright (c) 2023, Arm Limited and Contributors. All rights reserved.*