blob: 66b282c914e243887df2e75aadf883c46565420f [file] [log] [blame]
Paul Beesleyfc9ee362019-03-07 15:47:15 +00001Contributor's Guide
2===================
Douglas Raillardd7c21b72017-06-28 15:23:03 +01003
4Getting Started
5---------------
6
Louis Mayencourt72ef3d42019-03-22 11:47:22 +00007- Make sure you have a Github account and you are logged on
8 `developer.trustedfirmware.org`_.
Douglas Raillardd7c21b72017-06-28 15:23:03 +01009- Create an `issue`_ for your work if one does not already exist. This gives
Louis Mayencourt72ef3d42019-03-22 11:47:22 +000010 everyone visibility of whether others are working on something similar.
Douglas Raillardd7c21b72017-06-28 15:23:03 +010011
Douglas Raillardd7c21b72017-06-28 15:23:03 +010012 - If you intend to include Third Party IP in your contribution, please
13 raise a separate `issue`_ for this and ensure that the changes that
14 include Third Party IP are made on a separate topic branch.
15
John Tsichritzis2fd3d922019-05-28 13:13:39 +010016- Clone `Trusted Firmware-A`_ on your own machine as suggested on the
Louis Mayencourt72ef3d42019-03-22 11:47:22 +000017 `User Guide`_.
John Tsichritzis2fd3d922019-05-28 13:13:39 +010018- Create a local topic branch based on the `Trusted Firmware-A`_ ``master``
Douglas Raillardd7c21b72017-06-28 15:23:03 +010019 branch.
20
21Making Changes
22--------------
23
24- Make commits of logical units. See these general `Git guidelines`_ for
25 contributing to a project.
Louis Mayencourt72ef3d42019-03-22 11:47:22 +000026- Follow the `Coding Guidelines`_.
Douglas Raillardd7c21b72017-06-28 15:23:03 +010027
28 - Use the checkpatch.pl script provided with the Linux source tree. A
Louis Mayencourt72ef3d42019-03-22 11:47:22 +000029 Makefile target is provided for convenience (see the "Checking source code
30 style" section in the `User Guide`_).
Douglas Raillardd7c21b72017-06-28 15:23:03 +010031
32- Keep the commits on topic. If you need to fix another bug or make another
33 enhancement, please create a separate `issue`_ and address it on a separate
34 topic branch.
35- Avoid long commit series. If you do have a long series, consider whether
36 some commits should be squashed together or addressed in a separate topic.
37- Make sure your commit messages are in the proper format. If a commit fixes
Louis Mayencourt72ef3d42019-03-22 11:47:22 +000038 an `issue`_, include a reference.
Douglas Raillardd7c21b72017-06-28 15:23:03 +010039- Where appropriate, please update the documentation.
40
Louis Mayencourt72ef3d42019-03-22 11:47:22 +000041 - Consider whether the `User Guide`_, `Porting Guide`_, `Firmware Design`_
42 or other in-source documentation needs updating.
Douglas Raillardd7c21b72017-06-28 15:23:03 +010043 - Ensure that each changed file has the correct copyright and license
44 information. Files that entirely consist of contributions to this
Joanna Farley424ef752018-11-13 10:52:12 +000045 project should have a copyright notice and BSD-3-Clause SPDX license
46 identifier of the form as shown in `license.rst`_. Files that contain
47 changes to imported Third Party IP files should retain their original
48 copyright and license notices. For significant contributions you may
49 add your own copyright notice in following format:
Douglas Raillardd7c21b72017-06-28 15:23:03 +010050
51 ::
52
Joanna Farley424ef752018-11-13 10:52:12 +000053 Portions copyright (c) [XXXX-]YYYY, <OWNER>. All rights reserved.
Douglas Raillardd7c21b72017-06-28 15:23:03 +010054
55 where XXXX is the year of first contribution (if different to YYYY) and
Joanna Farley424ef752018-11-13 10:52:12 +000056 YYYY is the year of most recent contribution. <OWNER> is your name or
57 your company name.
Douglas Raillardd7c21b72017-06-28 15:23:03 +010058 - If you are submitting new files that you intend to be the technical
59 sub-maintainer for (for example, a new platform port), then also update
60 the `Maintainers`_ file.
61 - For topics with multiple commits, you should make all documentation
62 changes (and nothing else) in the last commit of the series. Otherwise,
63 include the documentation changes within the single commit.
64
Louis Mayencourt72ef3d42019-03-22 11:47:22 +000065- Please test your changes. As a minimum, ensure that Linux boots on the
66 Foundation FVP. See `Running the software on FVP`_ for more information. For
67 more extensive testing, consider running the `TF-A Tests`_ against your
68 patches.
Douglas Raillardd7c21b72017-06-28 15:23:03 +010069
70Submitting Changes
71------------------
72
73- Ensure that each commit in the series has at least one ``Signed-off-by:``
74 line, using your real name and email address. The names in the
Louis Mayencourt72ef3d42019-03-22 11:47:22 +000075 ``Signed-off-by:`` and ``Author:`` lines must match. If anyone else
76 contributes to the commit, they must also add their own ``Signed-off-by:``
77 line. By adding this line the contributor certifies the contribution is made
78 under the terms of the `Developer Certificate of Origin (DCO)`_.
79
80 More details may be found in the `Gerrit Signed-off-by Lines guidelines`_.
81
82- Ensure that each commit also has a unique ``Change-Id:`` line. If you have
83 cloned the repository with the "`Clone with commit-msg hook`" clone method
84 (as advised on the `User Guide`_), this should already be the case.
Douglas Raillardd7c21b72017-06-28 15:23:03 +010085
Louis Mayencourt72ef3d42019-03-22 11:47:22 +000086 More details may be found in the `Gerrit Change-Ids documentation`_.
87
88- Submit your changes for review at https://review.trustedfirmware.org
89 targeting the ``integration`` branch.
90
91 - The changes will then undergo further review and testing by the
92 `Maintainers`_. Any review comments will be made directly on your patch.
93 This may require you to do some rework.
94
95 Refer to the `Gerrit Uploading Changes documentation`_ for more details.
Douglas Raillardd7c21b72017-06-28 15:23:03 +010096
97- When the changes are accepted, the `Maintainers`_ will integrate them.
98
Louis Mayencourt72ef3d42019-03-22 11:47:22 +000099 - Typically, the `Maintainers`_ will merge the changes into the
100 ``integration`` branch.
101 - If the changes are not based on a sufficiently-recent commit, or if they
102 cannot be automatically rebased, then the `Maintainers`_ may rebase it on
103 the ``master`` branch or ask you to do so.
104 - After final integration testing, the changes will make their way into the
105 ``master`` branch. If a problem is found during integration, the merge
106 commit will be removed from the ``integration`` branch and the
107 `Maintainers`_ will ask you to create a new patch set to resolve the
Douglas Raillardd7c21b72017-06-28 15:23:03 +0100108 problem.
Douglas Raillardd7c21b72017-06-28 15:23:03 +0100109
Julius Wernercece91a2019-04-18 16:47:46 -0700110Binary Components
111-----------------
112
113- Platforms may depend on binary components submitted to the `Trusted Firmware
114 binary repository`_ if they require code that the contributor is unable or
115 unwilling to open-source. This should be used as a rare exception.
116- All binary components must follow the contribution guidelines (in particular
117 licensing rules) outlined in the `readme.rst <tf-binaries-readme_>`_ file of
118 the binary repository.
119- Binary components must be restricted to only the specific functionality that
120 cannot be open-sourced and must be linked into a larger open-source platform
121 port. The majority of the platform port must still be implemented in open
122 source. Platform ports that are merely a thin wrapper around a binary
123 component that contains all the actual code will not be accepted.
124- Only platform port code (i.e. in the ``plat/<vendor>`` directory) may rely on
125 binary components. Generic code must always be fully open-source.
126
Douglas Raillardd7c21b72017-06-28 15:23:03 +0100127--------------
128
Louis Mayencourt72ef3d42019-03-22 11:47:22 +0000129*Copyright (c) 2013-2019, Arm Limited and Contributors. All rights reserved.*
Douglas Raillardd7c21b72017-06-28 15:23:03 +0100130
Louis Mayencourt72ef3d42019-03-22 11:47:22 +0000131.. _developer.trustedfirmware.org: https://developer.trustedfirmware.org
132.. _issue: https://developer.trustedfirmware.org/project/board/1/
John Tsichritzis2fd3d922019-05-28 13:13:39 +0100133.. _Trusted Firmware-A: https://git.trustedfirmware.org/TF-A/trusted-firmware-a.git
Douglas Raillardd7c21b72017-06-28 15:23:03 +0100134.. _Git guidelines: http://git-scm.com/book/ch5-2.html
John Tsichritzis2fd3d922019-05-28 13:13:39 +0100135.. _Coding Guidelines: ./coding-guidelines.rst
136.. _User Guide: ../getting_started/user-guide.rst
137.. _Porting Guide: ../getting_started/porting-guide.rst
138.. _Firmware Design: ../design/firmware-design.rst
139.. _license.rst: ../license.rst
140.. _Acknowledgements: ../acknowledgements.rst
141.. _Maintainers: ../maintainers.rst
142.. _Running the software on FVP: ../getting_started/user-guide.rst#user-content-running-the-software-on-fvp
143.. _Developer Certificate of Origin (DCO): ../../dco.txt
Louis Mayencourt72ef3d42019-03-22 11:47:22 +0000144.. _Gerrit Uploading Changes documentation: https://review.trustedfirmware.org/Documentation/user-upload.html
145.. _Gerrit Signed-off-by Lines guidelines: https://review.trustedfirmware.org/Documentation/user-signedoffby.html
146.. _Gerrit Change-Ids documentation: https://review.trustedfirmware.org/Documentation/user-changeid.html
147.. _TF-A Tests: https://git.trustedfirmware.org/TF-A/tf-a-tests.git/about/
Julius Wernercece91a2019-04-18 16:47:46 -0700148.. _Trusted Firmware binary repository: https://review.trustedfirmware.org/admin/repos/tf-binaries
149.. _tf-binaries-readme: https://git.trustedfirmware.org/tf-binaries.git/tree/readme.rst