Adding upstream version 2.8.0+dfsg.upstream/2.8.0+dfsgupstream

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

1 files changed, 153 insertions, 0 deletions

diff --git a/docs/process/commit-style.rst b/docs/process/commit-style.rst
new file mode 100644
index 0000000..d7e937b
--- /dev/null
+++ b/docs/process/commit-style.rst
@@ -0,0 +1,153 @@
+Commit 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 detail why it does it. This helps to ensure that changes to the
+code-base are transparent and approachable to reviewers, and it allows us 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`_, include a reference.
+
+|TF-A| follows the `Conventional Commits`_ specification. All commits to the
+main repository 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)]
+
+The following example commit message demonstrates the use of the
+``refactor`` type and the ``amu`` scope:
+
+.. code::
+
+    refactor(amu): factor out register accesses
+
+    This change introduces a small set of register getters and setters to
+    avoid having to repeatedly mask and shift in complex code.
+
+    Change-Id: Ia372f60c5efb924cd6eeceb75112e635ad13d942
+    Signed-off-by: Chris Kay <chris.kay@arm.com>
+
+The following `types` are permissible and are strictly enforced:
+
++--------------+---------------------------------------------------------------+
+| Scope        | Description                                                   |
++==============+===============================================================+
+| ``feat``     | A new feature                                                 |
++--------------+---------------------------------------------------------------+
+| ``fix``      | A bug fix                                                     |
++--------------+---------------------------------------------------------------+
+| ``build``    | Changes that affect the build system or external dependencies |
++--------------+---------------------------------------------------------------+
+| ``ci``       | Changes to our 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                                              |
++--------------+---------------------------------------------------------------+
+
+The permissible `scopes` are more flexible, and we maintain a list of them in
+our :download:`changelog configuration file <../../changelog.yaml>`. Scopes in
+this file are organized by their changelog section, where each changelog section
+has a single scope that is considered to be blessed, and possibly several
+deprecated scopes. Please avoid using deprecated scopes.
+
+While we don't enforce scopes strictly, we do ask that commits use these if they
+can, or add their own if no appropriate one exists (see :ref:`Adding Scopes`).
+
+It's highly recommended that you use the tooling installed by the optional steps
+in the :ref:`prerequisites <Prerequisites>` guide to validate commit messages
+locally, as commitlint reports a live list of the acceptable scopes.
+
+.. _Adding Scopes:
+
+Adding Scopes
+-------------
+
+Scopes that are not present in the changelog configuration file are considered
+to be deprecated, and should be avoided. If you are adding a new component that
+does not yet have a designated scope, please add one.
+
+For example, if you are adding or making modifications to `Foo`'s latest and
+greatest new platform `Bar` then you would add it to the `Platforms` changelog
+sub-section, and the hierarchy should look something like this:
+
+.. code:: yaml
+
+    - title: Platforms
+
+      subsections:
+        - title: Foo
+          scope: foo
+
+          subsections:
+            - title: Bar
+              scope: bar
+
+When creating new scopes, try to keep them short and succinct, and use kebab
+case (``this-is-kebab-case``). Components with a product name (i.e. most
+platforms and some drivers) should use that name (e.g. ``gic600ae``,
+``flexspi``, ``stpmic1``), otherwise use a name that uniquely represents the
+component (e.g. ``marvell-comphy-3700``, ``rcar3-drivers``, ``a3720-uart``).
+
+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. By adding this line the contributor certifies the
+contribution is made under the terms of the :download:`Developer Certificate of
+Origin <../../dco.txt>`.
+
+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 either install the Node.js tools
+or 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`_.
+
+--------------
+
+*Copyright (c) 2021, Arm Limited and Contributors. All rights reserved.*
+
+.. _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
+.. _issue: https://developer.trustedfirmware.org/project/board/1/
+.. _quick summary: https://www.conventionalcommits.org/en/v1.0.0/#summary