1Contributor's Guide 2=================== 3 4Getting Started 5--------------- 6 7- Make sure you have a Github account and you are logged on both 8 `developer.trustedfirmware.org`_ and `review.trustedfirmware.org`_. 9 10- If you plan to contribute a major piece of work, it is usually a good idea to 11 start a discussion around it on the mailing list. This gives everyone 12 visibility of what is coming up, you might learn that somebody else is 13 already working on something similar or the community might be able to 14 provide some early input to help shaping the design of the feature. 15 16 If you intend to include Third Party IP in your contribution, please mention 17 it explicitly in the email thread and ensure that the changes that include 18 Third Party IP are made in a separate patch (or patch series). 19 20- Clone `Trusted Firmware-A`_ on your own machine as described in 21 :ref:`prerequisites_get_source`. 22 23- Create a local topic branch based on the `Trusted Firmware-A`_ ``master`` 24 branch. 25 26Making Changes 27-------------- 28 29- Ensure commits adhere to the the project's :ref:`Commit Style`. 30 31- Make commits of logical units. See these general `Git guidelines`_ for 32 contributing to a project. 33 34- Keep the commits on topic. If you need to fix another bug or make another 35 enhancement, please address it on a separate topic branch. 36 37- Split the patch in manageable units. Small patches are usually easier to 38 review so this will speed up the review process. 39 40- Avoid long commit series. If you do have a long series, consider whether 41 some commits should be squashed together or addressed in a separate topic. 42 43- Follow the :ref:`Coding Style` and :ref:`Coding Guidelines`. 44 45 - Use the checkpatch.pl script provided with the Linux source tree. A 46 Makefile target is provided for convenience, see :ref:`this 47 section<automatic-compliance-checking>` for more details. 48 49- Where appropriate, please update the documentation. 50 51 - Consider whether the :ref:`Porting Guide`, :ref:`Firmware Design` document 52 or other in-source documentation needs updating. 53 54 - If you are submitting new files that you intend to be the code owner for 55 (for example, a new platform port), then also update the 56 :ref:`code owners` file. 57 58 - For topics with multiple commits, you should make all documentation changes 59 (and nothing else) in the last commit of the series. Otherwise, include 60 the documentation changes within the single commit. 61 62.. _copyright-license-guidance: 63 64- Ensure that each changed file has the correct copyright and license 65 information. Files that entirely consist of contributions to this project 66 should have a copyright notice and BSD-3-Clause SPDX license identifier of 67 the form as shown in :ref:`license`. Files that contain changes to imported 68 Third Party IP files should retain their original copyright and license 69 notices. 70 71 For significant contributions you may add your own copyright notice in the 72 following format: 73 74 :: 75 76 Portions copyright (c) [XXXX-]YYYY, <OWNER>. All rights reserved. 77 78 where XXXX is the year of first contribution (if different to YYYY) and YYYY 79 is the year of most recent contribution. <OWNER> is your name or your company 80 name. 81 82- Ensure that each patch in the patch series compiles in all supported 83 configurations. Patches which do not compile will not be merged. 84 85- Please test your changes. As a minimum, ensure that Linux boots on the 86 Foundation FVP. See :ref:`Arm Fixed Virtual Platforms (FVP)` for more 87 information. For more extensive testing, consider running the `TF-A Tests`_ 88 against your patches. 89 90- Ensure that all CI automated tests pass. Failures should be fixed. They might 91 block a patch, depending on how critical they are. 92 93Submitting Changes 94------------------ 95 96- Submit your changes for review at https://review.trustedfirmware.org 97 targeting the ``integration`` branch. 98 99- Add reviewers for your patch: 100 101 - At least one code owner for each module modified by the patch. See the list 102 of modules and their :ref:`code owners`. 103 104 - At least one maintainer. See the list of :ref:`maintainers`. 105 106 - If some module has no code owner, try to identify a suitable (non-code 107 owner) reviewer. Running ``git blame`` on the module's source code can 108 help, as it shows who has been working the most recently on this area of 109 the code. 110 111 Alternatively, if it is impractical to identify such a reviewer, you might 112 send an email to the `TF-A mailing list`_ to broadcast your review request 113 to the community. 114 115 Note that self-reviewing a patch is prohibited, even if the patch author is 116 the only code owner of a module modified by the patch. Getting a second pair 117 of eyes on the code is essential to keep up with the quality standards the 118 project aspires to. 119 120- The changes will then undergo further review by the designated people. Any 121 review comments will be made directly on your patch. This may require you to 122 do some rework. For controversial changes, the discussion might be moved to 123 the `TF-A mailing list`_ to involve more of the community. 124 125 Refer to the `Gerrit Uploading Changes documentation`_ for more details. 126 127- The patch submission rules are the following. For a patch to be approved 128 and merged in the tree, it must get: 129 130 - One ``Code-Owner-Review+1`` for each of the modules modified by the patch. 131 - A ``Maintainer-Review+1``. 132 133 In the case where a code owner could not be found for a given module, 134 ``Code-Owner-Review+1`` is substituted by ``Code-Review+1``. 135 136 In addition to these various code review labels, the patch must also get a 137 ``Verified+1``. This is usually set by the Continuous Integration (CI) bot 138 when all automated tests passed on the patch. Sometimes, some of these 139 automated tests may fail for reasons unrelated to the patch. In this case, 140 the maintainers might (after analysis of the failures) override the CI bot 141 score to certify that the patch has been correctly tested. 142 143 In the event where the CI system lacks proper tests for a patch, the patch 144 author or a reviewer might agree to perform additional manual tests 145 in their review and the reviewer incorporates the review of the additional 146 testing in the ``Code-Review+1`` or ``Code-Owner-Review+1`` as applicable to 147 attest that the patch works as expected. Where possible additional tests should 148 be added to the CI system as a follow up task. For example, for a 149 platform-dependent patch where the said platform is not available in the CI 150 system's board farm. 151 152- When the changes are accepted, the :ref:`maintainers` will integrate them. 153 154 - Typically, the :ref:`maintainers` will merge the changes into the 155 ``integration`` branch. 156 157 - If the changes are not based on a sufficiently-recent commit, or if they 158 cannot be automatically rebased, then the :ref:`maintainers` may rebase it 159 on the ``integration`` branch or ask you to do so. 160 161 - After final integration testing, the changes will make their way into the 162 ``master`` branch. If a problem is found during integration, the 163 :ref:`maintainers` will request your help to solve the issue. They may 164 revert your patches and ask you to resubmit a reworked version of them or 165 they may ask you to provide a fix-up patch. 166 167Add Build Configurations 168------------------------ 169 170- TF-A uses Jenkins tool for Continuous Integration and testing activities. 171 Various CI Jobs are deployed which run tests on every patch before being 172 merged. So each of your patches go through a series of checks before they 173 get merged on to the master branch. 174 175- ``Coverity Scan analysis`` is one of the tests we perform on our source code 176 at regular intervals. We maintain a build script ``tf-cov-make`` which contains the 177 build configurations of various platforms in order to cover the entire source 178 code being analysed by Coverity. 179 180- When you submit your patches for review containing new source files, please 181 ensure to include them for the ``Coverity Scan analysis`` by adding the 182 respective build configurations in the ``tf-cov-make`` build script. 183 184- In this section you find the details on how to append your new build 185 configurations for Coverity Scan analysis: 186 187#. We maintain a separate repository named `tf-a-ci-scripts repository`_ 188 for placing all the test scripts which will be executed by the CI Jobs. 189 190#. In this repository, ``tf-cov-make`` script is located at 191 ``tf-a-ci-scripts/script/tf-coverity/tf-cov-make`` 192 193#. Edit `tf-cov-make`_ script by appending all the possible build configurations with 194 the specific ``build-flags`` relevant to your platform, so that newly added 195 source files get built and analysed by Coverity. 196 197#. For better understanding follow the below specified examples listed in the 198 ``tf-cov-make`` script. 199 200.. code:: shell 201 202 Example 1: 203 #Intel 204 make PLAT=stratix10 $(common_flags) all 205 make PLAT=agilex $(common_flags) all 206 207- In the above example there are two different SoCs ``stratix`` and ``agilex`` 208 under the Intel platform and the build configurations has been added suitably 209 to include most of their source files. 210 211.. code:: shell 212 213 Example 2: 214 #Hikey 215 make PLAT=hikey $(common_flags) ${TBB_OPTIONS} ENABLE_PMF=1 all 216 make PLAT=hikey960 $(common_flags) ${TBB_OPTIONS} all 217 make PLAT=poplar $(common_flags) all 218 219- In this case for ``Hikey`` boards additional ``build-flags`` has been included 220 along with the ``commom_flags`` to cover most of the files relevant to it. 221 222- Similar to this you can still find many other different build configurations 223 of various other platforms listed in the ``tf-cov-make`` script. Kindly refer 224 them and append your build configurations respectively. 225 226Binary Components 227----------------- 228 229- Platforms may depend on binary components submitted to the `Trusted Firmware 230 binary repository`_ if they require code that the contributor is unable or 231 unwilling to open-source. This should be used as a rare exception. 232- All binary components must follow the contribution guidelines (in particular 233 licensing rules) outlined in the `readme.rst <tf-binaries-readme_>`_ file of 234 the binary repository. 235- Binary components must be restricted to only the specific functionality that 236 cannot be open-sourced and must be linked into a larger open-source platform 237 port. The majority of the platform port must still be implemented in open 238 source. Platform ports that are merely a thin wrapper around a binary 239 component that contains all the actual code will not be accepted. 240- Only platform port code (i.e. in the ``plat/<vendor>`` directory) may rely on 241 binary components. Generic code must always be fully open-source. 242 243-------------- 244 245*Copyright (c) 2013-2021, Arm Limited and Contributors. All rights reserved.* 246 247.. _developer.trustedfirmware.org: https://developer.trustedfirmware.org 248.. _review.trustedfirmware.org: https://review.trustedfirmware.org 249.. _Trusted Firmware-A: https://git.trustedfirmware.org/TF-A/trusted-firmware-a.git 250.. _Git guidelines: http://git-scm.com/book/ch5-2.html 251.. _Gerrit Uploading Changes documentation: https://review.trustedfirmware.org/Documentation/user-upload.html 252.. _TF-A Tests: https://trustedfirmware-a-tests.readthedocs.io 253.. _Trusted Firmware binary repository: https://review.trustedfirmware.org/admin/repos/tf-binaries 254.. _tf-binaries-readme: https://git.trustedfirmware.org/tf-binaries.git/tree/readme.rst 255.. _TF-A mailing list: https://lists.trustedfirmware.org/mailman/listinfo/tf-a 256.. _tf-a-ci-scripts repository: https://git.trustedfirmware.org/ci/tf-a-ci-scripts.git/ 257.. _tf-cov-make: https://git.trustedfirmware.org/ci/tf-a-ci-scripts.git/tree/script/tf-coverity/tf-cov-make 258