docs/getting_started/commit-style.rst - hafnium/hafnium.git - TrustedFirmware Git Browser

 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

 Commit Linting
 --------------

 `Commitlint`_ helps enforce the conventional commits specification by
 providing commit message linting capabilities.

 Navigate to the Hafnium root directory. Node Version Manager (nvm) is
 required to install the Node.js dependency for Commitlint. To install
 nvm run the following command:

 .. code:: shell

   wget -qO- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.1/install.sh | bash

 To install Node.js, first reload the shell configuration to ensure that nvm is
 available.

 .. code:: shell

   source ~/.bashrc

 Run the following command to install Node.js:

 .. code:: shell

   nvm install 20

 To test that commit linting is working, navigate to the Hafnium root
 directory and run the following:

 .. code:: shell

   make commitlint

 By default this will apply linting to the most recent commit message.

 Additionally, you can lint any range of commit messages by setting the ``COMMITLINT_FROM`` and ``COMMITLINT_TO`` arguments.
 An example of this is as follows:

 .. code:: shell

   make commitlint COMMITLINT_FROM=HEAD~3 COMMITLINT_TO=HEAD

 .. _Commitlint: https://commitlint.js.org
 --------------

 *Copyright (c) 2023, Arm Limited and Contributors. All rights reserved.*
	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

	Commit Linting
	--------------

	`Commitlint`_ helps enforce the conventional commits specification by
	providing commit message linting capabilities.

	Navigate to the Hafnium root directory. Node Version Manager (nvm) is
	required to install the Node.js dependency for Commitlint. To install
	nvm run the following command:

	.. code:: shell

	wget -qO- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.1/install.sh \| bash

	To install Node.js, first reload the shell configuration to ensure that nvm is
	available.

	.. code:: shell

	source ~/.bashrc

	Run the following command to install Node.js:

	.. code:: shell

	nvm install 20

	To test that commit linting is working, navigate to the Hafnium root
	directory and run the following:

	.. code:: shell

	make commitlint

	By default this will apply linting to the most recent commit message.

	Additionally, you can lint any range of commit messages by setting the ``COMMITLINT_FROM`` and ``COMMITLINT_TO`` arguments.
	An example of this is as follows:

	.. code:: shell

	make commitlint COMMITLINT_FROM=HEAD~3 COMMITLINT_TO=HEAD

	.. _Commitlint: https://commitlint.js.org
	--------------

	Copyright (c) 2023, Arm Limited and Contributors. All rights reserved.