From e256cc63ae6a577af24b184783b54cc38e5ecc55 Mon Sep 17 00:00:00 2001 From: Sandrine Bailleux Date: Wed, 12 Aug 2020 11:29:46 +0200 Subject: [PATCH] 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 --- docs/process/contributing.rst | 49 +++++++++++++++++++++-------------- 1 file changed, 29 insertions(+), 20 deletions(-) diff --git a/docs/process/contributing.rst b/docs/process/contributing.rst index 5e490a967..bdfb6d6aa 100644 --- a/docs/process/contributing.rst +++ b/docs/process/contributing.rst @@ -19,6 +19,7 @@ Getting Started - 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 @@ Making Changes - 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 @@ Making Changes - 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: + - Consider whether the :ref:`Porting Guide`, :ref:`Firmware Design` document + or other in-source documentation needs updating. - :: - - Portions copyright (c) [XXXX-]YYYY, . All rights reserved. - - where XXXX is the year of first contribution (if different to YYYY) and - YYYY is the year of most recent contribution. 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, . All rights reserved. + + where XXXX is the year of first contribution (if different to YYYY) and YYYY + is the year of most recent contribution. 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