Dan Handley | 4def07d | 2018-03-01 18:44:00 +0000 | [diff] [blame] | 1 | Contributing to Trusted Firmware-A |
| 2 | ================================== |
Douglas Raillard | 6f62574 | 2017-06-28 15:23:03 +0100 | [diff] [blame] | 3 | |
| 4 | Getting Started |
| 5 | --------------- |
| 6 | |
| 7 | - Make sure you have a `GitHub account`_. |
| 8 | - Create an `issue`_ for your work if one does not already exist. This gives |
Dan Handley | 4def07d | 2018-03-01 18:44:00 +0000 | [diff] [blame] | 9 | everyone visibility of whether others are working on something similar. Arm |
| 10 | licensees may contact Arm directly via their partner managers instead if |
Douglas Raillard | 6f62574 | 2017-06-28 15:23:03 +0100 | [diff] [blame] | 11 | they prefer. |
| 12 | |
| 13 | - Note that the `issue`_ tracker for this project is in a separate |
| 14 | `issue tracking repository`_. Please follow the guidelines in that |
| 15 | repository. |
| 16 | - If you intend to include Third Party IP in your contribution, please |
| 17 | raise a separate `issue`_ for this and ensure that the changes that |
| 18 | include Third Party IP are made on a separate topic branch. |
| 19 | |
| 20 | - `Fork`_ `arm-trusted-firmware`_ on GitHub. |
| 21 | - Clone the fork to your own machine. |
| 22 | - Create a local topic branch based on the `arm-trusted-firmware`_ ``master`` |
| 23 | branch. |
| 24 | |
| 25 | Making Changes |
| 26 | -------------- |
| 27 | |
| 28 | - Make commits of logical units. See these general `Git guidelines`_ for |
| 29 | contributing to a project. |
Dan Handley | 4def07d | 2018-03-01 18:44:00 +0000 | [diff] [blame] | 30 | - Follow the `Linux coding style`_; this style is enforced for the TF-A |
| 31 | project (style errors only, not warnings). |
Douglas Raillard | 6f62574 | 2017-06-28 15:23:03 +0100 | [diff] [blame] | 32 | |
| 33 | - Use the checkpatch.pl script provided with the Linux source tree. A |
| 34 | Makefile target is provided for convenience (see section 2 in the |
| 35 | `User Guide`_). |
| 36 | |
| 37 | - Keep the commits on topic. If you need to fix another bug or make another |
| 38 | enhancement, please create a separate `issue`_ and address it on a separate |
| 39 | topic branch. |
| 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 | - Make sure your commit messages are in the proper format. If a commit fixes |
| 43 | a GitHub `issue`_, include a reference (e.g. |
| 44 | "fixes arm-software/tf-issues#45"); this ensures the `issue`_ is |
| 45 | `automatically closed`_ when merged into the `arm-trusted-firmware`_ ``master`` |
| 46 | branch. |
| 47 | - Where appropriate, please update the documentation. |
| 48 | |
| 49 | - Consider whether the `User Guide`_, `Porting Guide`_, `Firmware Design`_ or |
| 50 | other in-source documentation needs updating. |
| 51 | - Ensure that each changed file has the correct copyright and license |
| 52 | information. Files that entirely consist of contributions to this |
Joanna Farley | b79da22 | 2018-11-13 10:52:12 +0000 | [diff] [blame^] | 53 | project should have a copyright notice and BSD-3-Clause SPDX license |
| 54 | identifier of the form as shown in `license.rst`_. Files that contain |
| 55 | changes to imported Third Party IP files should retain their original |
| 56 | copyright and license notices. For significant contributions you may |
| 57 | add your own copyright notice in following format: |
Douglas Raillard | 6f62574 | 2017-06-28 15:23:03 +0100 | [diff] [blame] | 58 | |
| 59 | :: |
| 60 | |
Joanna Farley | b79da22 | 2018-11-13 10:52:12 +0000 | [diff] [blame^] | 61 | Portions copyright (c) [XXXX-]YYYY, <OWNER>. All rights reserved. |
Douglas Raillard | 6f62574 | 2017-06-28 15:23:03 +0100 | [diff] [blame] | 62 | |
| 63 | where XXXX is the year of first contribution (if different to YYYY) and |
Joanna Farley | b79da22 | 2018-11-13 10:52:12 +0000 | [diff] [blame^] | 64 | YYYY is the year of most recent contribution. <OWNER> is your name or |
| 65 | your company name. |
Douglas Raillard | 6f62574 | 2017-06-28 15:23:03 +0100 | [diff] [blame] | 66 | - If you are submitting new files that you intend to be the technical |
| 67 | sub-maintainer for (for example, a new platform port), then also update |
| 68 | the `Maintainers`_ file. |
| 69 | - For topics with multiple commits, you should make all documentation |
| 70 | changes (and nothing else) in the last commit of the series. Otherwise, |
| 71 | include the documentation changes within the single commit. |
| 72 | |
| 73 | - Please test your changes. As a minimum, ensure UEFI boots to the shell on |
| 74 | the Foundation FVP. See `Running the software on FVP`_ for more information. |
| 75 | |
| 76 | Submitting Changes |
| 77 | ------------------ |
| 78 | |
| 79 | - Ensure that each commit in the series has at least one ``Signed-off-by:`` |
| 80 | line, using your real name and email address. The names in the |
| 81 | ``Signed-off-by:`` and ``Author:`` lines must match. If anyone else contributes |
| 82 | to the commit, they must also add their own ``Signed-off-by:`` line. |
| 83 | By adding this line the contributor certifies the contribution is made under |
| 84 | the terms of the `Developer Certificate of Origin (DCO)`_. |
| 85 | - Push your local changes to your fork of the repository. |
| 86 | - Submit a `pull request`_ to the `arm-trusted-firmware`_ ``integration`` branch. |
| 87 | |
| 88 | - The changes in the `pull request`_ will then undergo further review and |
| 89 | testing by the `Maintainers`_. Any review comments will be made as |
| 90 | comments on the `pull request`_. This may require you to do some rework. |
| 91 | |
| 92 | - When the changes are accepted, the `Maintainers`_ will integrate them. |
| 93 | |
| 94 | - Typically, the `Maintainers`_ will merge the `pull request`_ into the |
| 95 | ``integration`` branch within the GitHub UI, creating a merge commit. |
| 96 | - Please avoid creating merge commits in the `pull request`_ itself. |
| 97 | - If the `pull request`_ is not based on a recent commit, the `Maintainers`_ |
| 98 | may rebase it onto the ``master`` branch first, or ask you to do this. |
| 99 | - If the `pull request`_ cannot be automatically merged, the `Maintainers`_ |
| 100 | will ask you to rebase it onto the ``master`` branch. |
| 101 | - After final integration testing, the `Maintainers`_ will push your merge |
| 102 | commit to the ``master`` branch. If a problem is found during integration, |
| 103 | the merge commit will be removed from the ``integration`` branch and the |
| 104 | `Maintainers`_ will ask you to create a new pull request to resolve the |
| 105 | problem. |
| 106 | - Please do not delete your topic branch until it is safely merged into |
| 107 | the ``master`` branch. |
| 108 | |
| 109 | -------------- |
| 110 | |
Dan Handley | 4def07d | 2018-03-01 18:44:00 +0000 | [diff] [blame] | 111 | *Copyright (c) 2013-2018, Arm Limited and Contributors. All rights reserved.* |
Douglas Raillard | 6f62574 | 2017-06-28 15:23:03 +0100 | [diff] [blame] | 112 | |
| 113 | .. _GitHub account: https://github.com/signup/free |
| 114 | .. _issue: https://github.com/ARM-software/tf-issues/issues |
| 115 | .. _issue tracking repository: https://github.com/ARM-software/tf-issues |
| 116 | .. _Fork: https://help.github.com/articles/fork-a-repo |
| 117 | .. _arm-trusted-firmware: https://github.com/ARM-software/arm-trusted-firmware |
| 118 | .. _Git guidelines: http://git-scm.com/book/ch5-2.html |
Sandrine Bailleux | fc5747f | 2018-09-24 17:26:57 +0200 | [diff] [blame] | 119 | .. _Linux coding style: https://github.com/torvalds/linux/blob/master/Documentation/process/coding-style.rst |
Douglas Raillard | 6f62574 | 2017-06-28 15:23:03 +0100 | [diff] [blame] | 120 | .. _User Guide: ./docs/user-guide.rst |
| 121 | .. _automatically closed: https://help.github.com/articles/closing-issues-via-commit-messages |
| 122 | .. _Porting Guide: ./docs/porting-guide.rst |
| 123 | .. _Firmware Design: ./docs/firmware-design.rst |
| 124 | .. _license.rst: ./license.rst |
| 125 | .. _Acknowledgements: ./acknowledgements.rst |
| 126 | .. _Maintainers: ./maintainers.rst |
| 127 | .. _Running the software on FVP: ./docs/user-guide.rst#user-content-running-the-software-on-fvp |
| 128 | .. _Developer Certificate of Origin (DCO): ./dco.txt |
| 129 | .. _pull request: https://help.github.com/articles/using-pull-requests |