doc: Refactor the contribution guidelines
Ensuring that each file changed by a patch has the correct copyright and
license information does not only apply to documentation files but to
all files within the source tree.
Move the guidance for copyright and license headers out of the paragraph
about updating the documentation to avoid any confusion.
Also do some cosmetic changes (adding empty lines, fitting in longer
lines in the 80-column limit, ...) to improve the readability of the RST
file.
Change-Id: I241a2089ca9db70f5a9f26b7070b947674b43265
Signed-off-by: Sandrine Bailleux <sandrine.bailleux@arm.com>
diff --git a/docs/process/contributing.rst b/docs/process/contributing.rst
index 5e490a9..bdfb6d6 100644
--- a/docs/process/contributing.rst
+++ b/docs/process/contributing.rst
@@ -19,6 +19,7 @@
- Clone `Trusted Firmware-A`_ on your own machine as described in
:ref:`prerequisites_get_source`.
+
- Create a local topic branch based on the `Trusted Firmware-A`_ ``master``
branch.
@@ -27,6 +28,7 @@
- Make commits of logical units. See these general `Git guidelines`_ for
contributing to a project.
+
- Follow the :ref:`Coding Style` and :ref:`Coding Guidelines`.
- Use the checkpatch.pl script provided with the Linux source tree. A
@@ -34,36 +36,43 @@
- Keep the commits on topic. If you need to fix another bug or make another
enhancement, please address it on a separate topic branch.
+
- Avoid long commit series. If you do have a long series, consider whether
some commits should be squashed together or addressed in a separate topic.
+
- Make sure your commit messages are in the proper format. If a commit fixes
an `issue`_, include a reference.
-- Where appropriate, please update the documentation.
-
- - Consider whether the :ref:`Porting Guide`,
- :ref:`Firmware Design` document or other in-source documentation needs
- updating.
- - Ensure that each changed file has the correct copyright and license
- information. Files that entirely consist of contributions to this
- project should have a copyright notice and BSD-3-Clause SPDX license
- identifier of the form as shown in :ref:`license`. Files that contain
- changes to imported Third Party IP files should retain their original
- copyright and license notices. For significant contributions you may
- add your own copyright notice in following format:
- ::
+- Where appropriate, please update the documentation.
- Portions copyright (c) [XXXX-]YYYY, <OWNER>. All rights reserved.
+ - Consider whether the :ref:`Porting Guide`, :ref:`Firmware Design` document
+ or other in-source documentation needs updating.
- where XXXX is the year of first contribution (if different to YYYY) and
- YYYY is the year of most recent contribution. <OWNER> is your name or
- your company name.
- If you are submitting new files that you intend to be the code owner for
(for example, a new platform port), then also update the
:ref:`code owners` file.
- - For topics with multiple commits, you should make all documentation
- changes (and nothing else) in the last commit of the series. Otherwise,
- include the documentation changes within the single commit.
+
+ - For topics with multiple commits, you should make all documentation changes
+ (and nothing else) in the last commit of the series. Otherwise, include
+ the documentation changes within the single commit.
+
+- Ensure that each changed file has the correct copyright and license
+ information. Files that entirely consist of contributions to this project
+ should have a copyright notice and BSD-3-Clause SPDX license identifier of
+ the form as shown in :ref:`license`. Files that contain changes to imported
+ Third Party IP files should retain their original copyright and license
+ notices.
+
+ For significant contributions you may add your own copyright notice in the
+ following format:
+
+ ::
+
+ Portions copyright (c) [XXXX-]YYYY, <OWNER>. All rights reserved.
+
+ where XXXX is the year of first contribution (if different to YYYY) and YYYY
+ is the year of most recent contribution. <OWNER> is your name or your company
+ name.
- Please test your changes. As a minimum, ensure that Linux boots on the
Foundation FVP. See :ref:`Arm Fixed Virtual Platforms (FVP)` for more