blob: f569fcbe7a5e0e7a59d4ed71c658d1ed79393396 [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
Paul Beesleyd2fcc4e2019-05-29 13:59:40 +010016- Clone `Trusted Firmware-A`_ on your own machine as described in
17 :ref:`prerequisites_get_source`.
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.
Paul Beesleyf8640672019-04-12 14:19:42 +010026- Follow the :ref:`Coding Style & Guidelines`.
Douglas Raillardd7c21b72017-06-28 15:23:03 +010027
28 - Use the checkpatch.pl script provided with the Linux source tree. A
Paul Beesleyd2fcc4e2019-05-29 13:59:40 +010029 Makefile target is provided for convenience.
Douglas Raillardd7c21b72017-06-28 15:23:03 +010030
31- Keep the commits on topic. If you need to fix another bug or make another
32 enhancement, please create a separate `issue`_ and address it on a separate
33 topic branch.
34- Avoid long commit series. If you do have a long series, consider whether
35 some commits should be squashed together or addressed in a separate topic.
36- Make sure your commit messages are in the proper format. If a commit fixes
Louis Mayencourt72ef3d42019-03-22 11:47:22 +000037 an `issue`_, include a reference.
Douglas Raillardd7c21b72017-06-28 15:23:03 +010038- Where appropriate, please update the documentation.
39
Paul Beesleyd2fcc4e2019-05-29 13:59:40 +010040 - Consider whether the :ref:`Porting Guide`,
41 :ref:`Firmware Design` document or other in-source documentation needs
42 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
Paul Beesleyf8640672019-04-12 14:19:42 +010046 identifier of the form as shown in :ref:`license`. Files that contain
Joanna Farley424ef752018-11-13 10:52:12 +000047 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
Paul Beesleyf8640672019-04-12 14:19:42 +010060 the :ref:`maintainers` file.
Douglas Raillardd7c21b72017-06-28 15:23:03 +010061 - 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
Paul Beesleyd2fcc4e2019-05-29 13:59:40 +010066 Foundation FVP. See :ref:`Arm Fixed Virtual Platforms (FVP)` for more
67 information. For more extensive testing, consider running the `TF-A Tests`_
68 against your 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
Paul Beesleyf8640672019-04-12 14:19:42 +010078 under the terms of the
79 :download:`Developer Certificate of Origin <../../dco.txt>`.
Louis Mayencourt72ef3d42019-03-22 11:47:22 +000080
81 More details may be found in the `Gerrit Signed-off-by Lines guidelines`_.
82
83- Ensure that each commit also has a unique ``Change-Id:`` line. If you have
84 cloned the repository with the "`Clone with commit-msg hook`" clone method
Paul Beesleyd2fcc4e2019-05-29 13:59:40 +010085 (following the :ref:`Prerequisites` document), this should already be the
86 case.
Douglas Raillardd7c21b72017-06-28 15:23:03 +010087
Louis Mayencourt72ef3d42019-03-22 11:47:22 +000088 More details may be found in the `Gerrit Change-Ids documentation`_.
89
90- Submit your changes for review at https://review.trustedfirmware.org
91 targeting the ``integration`` branch.
92
93 - The changes will then undergo further review and testing by the
Paul Beesleyf8640672019-04-12 14:19:42 +010094 :ref:`maintainers`. Any review comments will be made directly on your
95 patch. This may require you to do some rework.
Louis Mayencourt72ef3d42019-03-22 11:47:22 +000096
97 Refer to the `Gerrit Uploading Changes documentation`_ for more details.
Douglas Raillardd7c21b72017-06-28 15:23:03 +010098
Paul Beesleyf8640672019-04-12 14:19:42 +010099- When the changes are accepted, the :ref:`maintainers` will integrate them.
Douglas Raillardd7c21b72017-06-28 15:23:03 +0100100
Paul Beesleyf8640672019-04-12 14:19:42 +0100101 - Typically, the :ref:`maintainers` will merge the changes into the
Louis Mayencourt72ef3d42019-03-22 11:47:22 +0000102 ``integration`` branch.
103 - If the changes are not based on a sufficiently-recent commit, or if they
Paul Beesleyf8640672019-04-12 14:19:42 +0100104 cannot be automatically rebased, then the :ref:`maintainers` may rebase it
105 on the ``master`` branch or ask you to do so.
Louis Mayencourt72ef3d42019-03-22 11:47:22 +0000106 - After final integration testing, the changes will make their way into the
107 ``master`` branch. If a problem is found during integration, the merge
108 commit will be removed from the ``integration`` branch and the
Paul Beesleyf8640672019-04-12 14:19:42 +0100109 :ref:`maintainers` will ask you to create a new patch set to resolve the
Douglas Raillardd7c21b72017-06-28 15:23:03 +0100110 problem.
Douglas Raillardd7c21b72017-06-28 15:23:03 +0100111
Julius Wernercece91a2019-04-18 16:47:46 -0700112Binary Components
113-----------------
114
115- Platforms may depend on binary components submitted to the `Trusted Firmware
116 binary repository`_ if they require code that the contributor is unable or
117 unwilling to open-source. This should be used as a rare exception.
118- All binary components must follow the contribution guidelines (in particular
119 licensing rules) outlined in the `readme.rst <tf-binaries-readme_>`_ file of
120 the binary repository.
121- Binary components must be restricted to only the specific functionality that
122 cannot be open-sourced and must be linked into a larger open-source platform
123 port. The majority of the platform port must still be implemented in open
124 source. Platform ports that are merely a thin wrapper around a binary
125 component that contains all the actual code will not be accepted.
126- Only platform port code (i.e. in the ``plat/<vendor>`` directory) may rely on
127 binary components. Generic code must always be fully open-source.
128
Douglas Raillardd7c21b72017-06-28 15:23:03 +0100129--------------
130
Louis Mayencourt72ef3d42019-03-22 11:47:22 +0000131*Copyright (c) 2013-2019, Arm Limited and Contributors. All rights reserved.*
Douglas Raillardd7c21b72017-06-28 15:23:03 +0100132
Louis Mayencourt72ef3d42019-03-22 11:47:22 +0000133.. _developer.trustedfirmware.org: https://developer.trustedfirmware.org
134.. _issue: https://developer.trustedfirmware.org/project/board/1/
John Tsichritzis2fd3d922019-05-28 13:13:39 +0100135.. _Trusted Firmware-A: https://git.trustedfirmware.org/TF-A/trusted-firmware-a.git
Douglas Raillardd7c21b72017-06-28 15:23:03 +0100136.. _Git guidelines: http://git-scm.com/book/ch5-2.html
Louis Mayencourt72ef3d42019-03-22 11:47:22 +0000137.. _Gerrit Uploading Changes documentation: https://review.trustedfirmware.org/Documentation/user-upload.html
138.. _Gerrit Signed-off-by Lines guidelines: https://review.trustedfirmware.org/Documentation/user-signedoffby.html
139.. _Gerrit Change-Ids documentation: https://review.trustedfirmware.org/Documentation/user-changeid.html
140.. _TF-A Tests: https://git.trustedfirmware.org/TF-A/tf-a-tests.git/about/
Julius Wernercece91a2019-04-18 16:47:46 -0700141.. _Trusted Firmware binary repository: https://review.trustedfirmware.org/admin/repos/tf-binaries
142.. _tf-binaries-readme: https://git.trustedfirmware.org/tf-binaries.git/tree/readme.rst