andrius
/
arm-trusted-firmware
1
0
Fork 0
Code Issues Pull Requests Releases Wiki Activity

Merge pull request #1918 from lmayencourt/lm/contrib_guidelines 

doc: Update contribution guidelines
This commit is contained in:
Antonio Niño Díaz 2019-04-03 11:20:38 +01:00 committed by GitHub
parent 1348b6d137 63fdda2d98
commit 18d4d113ec
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
4 changed files with 117 additions and 129 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

107
contributing.rst
View File

@ -4,22 +4,18 @@ Contributing to Trusted Firmware-A
Getting Started Getting Started
--------------- ---------------
- Make sure you have a `GitHub account`_. - Make sure you have a Github account and you are logged on
`developer.trustedfirmware.org`_.
- Create an `issue`_ for your work if one does not already exist. This gives - Create an `issue`_ for your work if one does not already exist. This gives
everyone visibility of whether others are working on something similar. Arm everyone visibility of whether others are working on something similar.
licensees may contact Arm directly via their partner managers instead if
they prefer.
- Note that the `issue`_ tracker for this project is in a separate
`issue tracking repository`_. Please follow the guidelines in that
repository.
- If you intend to include Third Party IP in your contribution, please - If you intend to include Third Party IP in your contribution, please
raise a separate `issue`_ for this and ensure that the changes that raise a separate `issue`_ for this and ensure that the changes that
include Third Party IP are made on a separate topic branch. include Third Party IP are made on a separate topic branch.
- `Fork`_ `arm-trusted-firmware`_ on GitHub. - Clone `arm-trusted-firmware-a`_ on your own machine as suggested on the
- Clone the fork to your own machine. `User Guide`_.
- Create a local topic branch based on the `arm-trusted-firmware`_ ``master`` - Create a local topic branch based on the `arm-trusted-firmware-a`_ ``master``
branch. branch.
Making Changes Making Changes
@ -27,12 +23,11 @@ Making Changes
- Make commits of logical units. See these general `Git guidelines`_ for - Make commits of logical units. See these general `Git guidelines`_ for
contributing to a project. contributing to a project.
- Follow the `Linux coding style`_; this style is enforced for the TF-A - Follow the `Coding Guidelines`_.
project (style errors only, not warnings).
- Use the checkpatch.pl script provided with the Linux source tree. A - Use the checkpatch.pl script provided with the Linux source tree. A
Makefile target is provided for convenience (see section 2 in the Makefile target is provided for convenience (see the "Checking source code
`User Guide`_). style" section in the `User Guide`_).
- Keep the commits on topic. If you need to fix another bug or make another - Keep the commits on topic. If you need to fix another bug or make another
enhancement, please create a separate `issue`_ and address it on a separate enhancement, please create a separate `issue`_ and address it on a separate
@ -40,14 +35,11 @@ Making Changes
- Avoid long commit series. If you do have a long series, consider whether - 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. 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 - Make sure your commit messages are in the proper format. If a commit fixes
a GitHub `issue`_, include a reference (e.g. an `issue`_, include a reference.
"fixes arm-software/tf-issues#45"); this ensures the `issue`_ is
`automatically closed`_ when merged into the `arm-trusted-firmware`_ ``master``
branch.
- Where appropriate, please update the documentation. - Where appropriate, please update the documentation.
- Consider whether the `User Guide`_, `Porting Guide`_, `Firmware Design`_ or - Consider whether the `User Guide`_, `Porting Guide`_, `Firmware Design`_
other in-source documentation needs updating. or other in-source documentation needs updating.
- Ensure that each changed file has the correct copyright and license - Ensure that each changed file has the correct copyright and license
information. Files that entirely consist of contributions to this information. Files that entirely consist of contributions to this
project should have a copyright notice and BSD-3-Clause SPDX license project should have a copyright notice and BSD-3-Clause SPDX license
@ -70,55 +62,61 @@ Making Changes
changes (and nothing else) in the last commit of the series. Otherwise, changes (and nothing else) in the last commit of the series. Otherwise,
include the documentation changes within the single commit. include the documentation changes within the single commit.
- Please test your changes. As a minimum, ensure UEFI boots to the shell on - Please test your changes. As a minimum, ensure that Linux boots on the
the Foundation FVP. See `Running the software on FVP`_ for more information. Foundation FVP. See `Running the software on FVP`_ for more information. For
more extensive testing, consider running the `TF-A Tests`_ against your
patches.
Submitting Changes Submitting Changes
------------------ ------------------
- Ensure that each commit in the series has at least one ``Signed-off-by:`` - Ensure that each commit in the series has at least one ``Signed-off-by:``
line, using your real name and email address. The names in the line, using your real name and email address. The names in the
``Signed-off-by:`` and ``Author:`` lines must match. If anyone else contributes ``Signed-off-by:`` and ``Author:`` lines must match. If anyone else
to the commit, they must also add their own ``Signed-off-by:`` line. contributes to the commit, they must also add their own ``Signed-off-by:``
By adding this line the contributor certifies the contribution is made under line. By adding this line the contributor certifies the contribution is made
the terms of the `Developer Certificate of Origin (DCO)`_. under the terms of the `Developer Certificate of Origin (DCO)`_.
- Push your local changes to your fork of the repository.
- Submit a `pull request`_ to the `arm-trusted-firmware`_ ``integration`` branch.
- The changes in the `pull request`_ will then undergo further review and More details may be found in the `Gerrit Signed-off-by Lines guidelines`_.
testing by the `Maintainers`_. Any review comments will be made as
comments on the `pull request`_. This may require you to do some rework. - Ensure that each commit also has a unique ``Change-Id:`` line. If you have
cloned the repository with the "`Clone with commit-msg hook`" clone method
(as advised on the `User Guide`_), this should already be the case.
More details may be found in the `Gerrit Change-Ids documentation`_.
- Submit your changes for review at https://review.trustedfirmware.org
targeting the ``integration`` branch.
- The changes will then undergo further review and testing by the
`Maintainers`_. Any review comments will be made directly on your patch.
This may require you to do some rework.
Refer to the `Gerrit Uploading Changes documentation`_ for more details.
- When the changes are accepted, the `Maintainers`_ will integrate them. - When the changes are accepted, the `Maintainers`_ will integrate them.
- Typically, the `Maintainers`_ will merge the `pull request`_ into the - Typically, the `Maintainers`_ will merge the changes into the
``integration`` branch within the GitHub UI, creating a merge commit. ``integration`` branch.
- Please avoid creating merge commits in the `pull request`_ itself. - If the changes are not based on a sufficiently-recent commit, or if they
- If the `pull request`_ is not based on a recent commit, the `Maintainers`_ cannot be automatically rebased, then the `Maintainers`_ may rebase it on
may rebase it onto the ``master`` branch first, or ask you to do this. the ``master`` branch or ask you to do so.
- If the `pull request`_ cannot be automatically merged, the `Maintainers`_ - After final integration testing, the changes will make their way into the
will ask you to rebase it onto the ``master`` branch. ``master`` branch. If a problem is found during integration, the merge
- After final integration testing, the `Maintainers`_ will push your merge commit will be removed from the ``integration`` branch and the
commit to the ``master`` branch. If a problem is found during integration, `Maintainers`_ will ask you to create a new patch set to resolve the
the merge commit will be removed from the ``integration`` branch and the
`Maintainers`_ will ask you to create a new pull request to resolve the
problem. problem.
- Please do not delete your topic branch until it is safely merged into
the ``master`` branch.
-------------- --------------
*Copyright (c) 2013-2018, Arm Limited and Contributors. All rights reserved.* *Copyright (c) 2013-2019, Arm Limited and Contributors. All rights reserved.*
.. _GitHub account: https://github.com/signup/free .. _developer.trustedfirmware.org: https://developer.trustedfirmware.org
.. _issue: https://github.com/ARM-software/tf-issues/issues .. _issue: https://developer.trustedfirmware.org/project/board/1/
.. _issue tracking repository: https://github.com/ARM-software/tf-issues .. _arm-trusted-firmware-a: https://git.trustedfirmware.org/TF-A/trusted-firmware-a.git
.. _Fork: https://help.github.com/articles/fork-a-repo
.. _arm-trusted-firmware: https://github.com/ARM-software/arm-trusted-firmware
.. _Git guidelines: http://git-scm.com/book/ch5-2.html .. _Git guidelines: http://git-scm.com/book/ch5-2.html
.. _Linux coding style: https://github.com/torvalds/linux/blob/master/Documentation/process/coding-style.rst .. _Coding Guidelines: ./docs/coding-guidelines.rst
.. _User Guide: ./docs/user-guide.rst .. _User Guide: ./docs/user-guide.rst
.. _automatically closed: https://help.github.com/articles/closing-issues-via-commit-messages
.. _Porting Guide: ./docs/porting-guide.rst .. _Porting Guide: ./docs/porting-guide.rst
.. _Firmware Design: ./docs/firmware-design.rst .. _Firmware Design: ./docs/firmware-design.rst
.. _license.rst: ./license.rst .. _license.rst: ./license.rst
@ -126,4 +124,7 @@ Submitting Changes
.. _Maintainers: ./maintainers.rst .. _Maintainers: ./maintainers.rst
.. _Running the software on FVP: ./docs/user-guide.rst#user-content-running-the-software-on-fvp .. _Running the software on FVP: ./docs/user-guide.rst#user-content-running-the-software-on-fvp
.. _Developer Certificate of Origin (DCO): ./dco.txt .. _Developer Certificate of Origin (DCO): ./dco.txt
.. _pull request: https://help.github.com/articles/using-pull-requests .. _Gerrit Uploading Changes documentation: https://review.trustedfirmware.org/Documentation/user-upload.html
.. _Gerrit Signed-off-by Lines guidelines: https://review.trustedfirmware.org/Documentation/user-signedoffby.html
.. _Gerrit Change-Ids documentation: https://review.trustedfirmware.org/Documentation/user-changeid.html
.. _TF-A Tests: https://git.trustedfirmware.org/TF-A/tf-a-tests.git/about/

110
docs/frequently-asked-questions.rst
View File

@ -1,91 +1,79 @@
Frequently-Asked Questions (FAQ) Frequently-Asked Questions (FAQ)
================================ ================================
How do I update a Pull Request? How do I update my changes?
------------------------------- ---------------------------
Often it is necessary to update a Pull Request (PR) before it is merged. When Often it is necessary to update your patch set before it is merged. Refer to the
you push to the source topic branch of an open PR, the PR is automatically `Gerrit Upload Patch Set documentation`_ on how to do so.
updated with the new commits.
If you need to modify existing commits in the PR (for example following review If you need to modify an existing patch set with multiple commits, refer to the
comments), then use the ``--force`` option when pushing. Any comments that apply `Gerrit Replace Changes documentation`_.
to previous versions of the PR are retained in the PR. Sometimes it may be
confusing whether comments apply to the current or a previous version of the PR,
especially if there are several rounds of rework. In this case, you may be asked
to close the PR and create a new one with the latest commits. The new PR should
have a version appended to the name (e.g. "My topic v2") and you should create a
link to the old PR so that reviewers can easily find previous versions.
When the PR is finally merged, you will be given the option of deleting your How long will my changes take to merge into ``integration``?
topic branch. It is recommended you delete this (and any previous topic branch ------------------------------------------------------------
versions) to avoid polluting your fork with obsolete branches.
How long will my Pull Request take to merge?
--------------------------------------------
This can vary a lot, depending on: This can vary a lot, depending on:
* How important the Pull Request (PR) is considered by the TF maintainers. Where * How important the patch set is considered by the TF maintainers. Where
possible, you should indicate the required timescales for merging the PR and possible, you should indicate the required timescales for merging the patch
the impact of any delay. set and the impact of any delay. Feel free to add a comment to your patch set
to get an estimate of when it will be merged.
* The quality of the PR. PRs are likely to be merged quicker if they follow the * The quality of the patch set. Patches are likely to be merged more quickly if
coding guidelines, have already had some code review, and have been they follow the coding guidelines, have already had some code review, and have
appropriately tested. Note that PRs from Arm engineers go through an internal been appropriately tested.
review process before appearing on GitHub, therefore may appear to be merged
more quickly.
* The impact of the PR. For example, a PR that changes a key generic API is * The impact of the patch set. For example, a patch that changes a key generic
likely to receive much greater scrutiny than a local change to a specific API is likely to receive much greater scrutiny than a local change to a
platform port. specific platform port.
* How much opportunity for external review is required. For example, the TF * How much opportunity for external review is required. For example, the TF
maintainers may not wait for external review comments to merge trivial maintainers may not wait for external review comments to merge trivial
bug-fixes but may wait up to a week to merge major changes, or ones requiring bug-fixes but may wait up to a week to merge major changes, or ones requiring
feedback from specific parties. feedback from specific parties.
* How many other topics need to be integrated and the risk of conflict between * How many other patch sets are waiting to be integrated and the risk of
the topics. conflict between the topics.
* Is there a code freeze in place in preparation for the release. Please refer * If there is a code freeze in place in preparation for the release. Please
the `release information`_ for more details. refer the `release information`_ for more details.
* The workload of the TF maintainers. * The workload of the TF maintainers.
Feel free to add a comment to your PR to get an estimate of when it will How long will it take for my changes to go from ``integration`` to ``master``?
be merged. ------------------------------------------------------------------------------
How long will it take for my merged Pull Request to go from ``integration`` to ``master``? This depends on how many concurrent patches are being processed at the same
------------------------------------------------------------------------------------------ time. In simple cases where all potential regressions have already been tested,
the delay will be less than 1 day. If the TF maintainers are trying to merge
This depends on how many concurrent Pull Requests (PRs) are being processed at several things over the course of a few days, it might take up to a week.
the same time. In simple cases where all potential regressions have already been
tested, the delay will be less than 1 day. If the TF maintainers are trying to
merge several things over the course of a few days, it might take up to a week.
Typically, it will be 1-2 days. Typically, it will be 1-2 days.
The worst case is if the TF maintainers are trying to make a release while also The worst case is if the TF maintainers are trying to make a release while also
receiving PRs that will not be merged into the release. In this case, the PRs receiving patches that will not be merged into the release. In this case, the
will be merged onto ``integration``, which will temporarily diverge from the patches will be merged onto ``integration``, which will temporarily diverge from
release branch. The ``integration`` branch will be rebased onto ``master`` after the release branch. The ``integration`` branch will be rebased onto ``master``
the release, and then ``master`` will be fast-forwarded to ``integration`` 1-2 after the release, and then ``master`` will be fast-forwarded to ``integration``
days later. This whole process could take up 4 weeks. Please refer the `release 1-2 days later. This whole process could take up 4 weeks. Please refer the
information`_ for code freeze dates. The TF maintainers will inform the PR owner `release information`_ for code freeze dates. The TF maintainers will inform the
if this is going to happen. patch owner if this is going to happen.
It is OK to create a PR based on commits that are only available in It is OK to create a patch based on commits that are only available in
``integration`` or another PR, rather than ``master``. There is a risk that the ``integration`` or another patch set, rather than ``master``. There is a risk
dependency commits will change (for example due to PR rework or integration that the dependency commits will change (for example due to patch set rework or
problems). If this happens, the dependent PR will need reworking. integration problems). If this happens, the dependent patch will need reworking.
What are these strange comments in my Pull Request? What are these strange comments in my changes?
--------------------------------------------------- ----------------------------------------------
For example, comments like "Can one of the admins verify this patch?" or "test All the comments from ``ci-bot-user`` are associated with Continuous Integration
this please". These are associated with Arm's Continuous Integration infrastructure. The links published on the comment are not currently accessible,
infrastructure and can be safely ignored. Those who are curious can see the but would be after the CI has been transitioned to `trustedfirmware.org`_.
documentation for `this Jenkins plugin`_ for more details. Please refer to https://github.com/ARM-software/tf-issues/issues/681 for more
details on the timelines.
.. _release information: release-information.rst .. _release information: release-information.rst
.. _this Jenkins plugin: https://wiki.jenkins-ci.org/display/JENKINS/GitHub+pull+request+builder+plugin .. _Gerrit Upload Patch Set documentation: https://review.trustedfirmware.org/Documentation/intro-user.html#upload-patch-set
.. _Gerrit Replace Changes documentation: https://review.trustedfirmware.org/Documentation/user-upload.html#push_replace
.. _trustedfirmware.org: https://www.trustedfirmware.org/

13
docs/user-guide.rst
View File

@ -81,11 +81,11 @@ In addition, the following optional packages and tools may be needed:
Getting the TF-A source code Getting the TF-A source code
---------------------------- ----------------------------
Download the TF-A source code from Github: Clone the repository from the Gerrit server. The project details may be found
on the `arm-trusted-firmware-a project page`_. We recommend the "`Clone with
:: commit-msg hook`" clone method, which will setup the git commit hook that
automatically generates and inserts appropriate `Change-Id:` lines in your
git clone https://github.com/ARM-software/arm-trusted-firmware.git commit messages.
Checking source code style Checking source code style
~~~~~~~~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~~~~~~~~
@ -2101,6 +2101,7 @@ wakeup interrupt from RTC.
.. _Instructions for using Linaro's deliverables on Juno: https://community.arm.com/dev-platforms/w/docs/303/juno .. _Instructions for using Linaro's deliverables on Juno: https://community.arm.com/dev-platforms/w/docs/303/juno
.. _Arm Platforms Portal: https://community.arm.com/dev-platforms/ .. _Arm Platforms Portal: https://community.arm.com/dev-platforms/
.. _Development Studio 5 (DS-5): https://developer.arm.com/products/software-development-tools/ds-5-development-studio .. _Development Studio 5 (DS-5): https://developer.arm.com/products/software-development-tools/ds-5-development-studio
.. _arm-trusted-firmware-a project page: https://review.trustedfirmware.org/admin/projects/TF-A/trusted-firmware-a
.. _`Linux Coding Style`: https://www.kernel.org/doc/html/latest/process/coding-style.html .. _`Linux Coding Style`: https://www.kernel.org/doc/html/latest/process/coding-style.html
.. _Linux master tree: https://github.com/torvalds/linux/tree/master/ .. _Linux master tree: https://github.com/torvalds/linux/tree/master/
.. _Dia: https://wiki.gnome.org/Apps/Dia/Download .. _Dia: https://wiki.gnome.org/Apps/Dia/Download
@ -2118,4 +2119,4 @@ wakeup interrupt from RTC.
.. _PSCI: http://infocenter.arm.com/help/topic/com.arm.doc.den0022d/Power_State_Coordination_Interface_PDD_v1_1_DEN0022D.pdf .. _PSCI: http://infocenter.arm.com/help/topic/com.arm.doc.den0022d/Power_State_Coordination_Interface_PDD_v1_1_DEN0022D.pdf
.. _Secure Partition Manager Design guide: secure-partition-manager-design.rst .. _Secure Partition Manager Design guide: secure-partition-manager-design.rst
.. _`Trusted Firmware-A Coding Guidelines`: coding-guidelines.rst .. _`Trusted Firmware-A Coding Guidelines`: coding-guidelines.rst
_`Library at ROM`: romlib-design.rst .. _`Library at ROM`: romlib-design.rst

16
readme.rst
View File

@ -252,15 +252,13 @@ Still to come
- Ongoing security hardening, optimization and quality improvements. - Ongoing security hardening, optimization and quality improvements.
For a full list of detailed issues in the current code, please see the `Change For a full list of detailed issues in the current code, please see the `Change
Log`_ and the `GitHub issue tracker`_. Log`_ and the `issue tracker`_.
Getting started Getting started
--------------- ---------------
Get the TF-A source code from `GitHub`_. See the `User Guide`_ for instructions on how to download, install, build and
use TF-A with the Arm `FVP`_\ s.
See the `User Guide`_ for instructions on how to install, build and use TF-A
with the Arm `FVP`_\ s.
See the `Firmware Design`_ for information on how TF-A works. See the `Firmware Design`_ for information on how TF-A works.
@ -282,7 +280,7 @@ IRC channel
Development discussion takes place on the #trusted-firmware-a channel Development discussion takes place on the #trusted-firmware-a channel
on the Freenode IRC network. This is not an official support channel. on the Freenode IRC network. This is not an official support channel.
If you have an issue to raise, please use the `GitHub issue tracker`_. If you have an issue to raise, please use the `issue tracker`_.
Feedback and support Feedback and support
~~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~~
@ -290,7 +288,7 @@ Feedback and support
Arm welcomes any feedback on TF-A. If you think you have found a security Arm welcomes any feedback on TF-A. If you think you have found a security
vulnerability, please report this using the process defined in the TF-A vulnerability, please report this using the process defined in the TF-A
`Security Center`_. For all other feedback, please use the `Security Center`_. For all other feedback, please use the
`GitHub issue tracker`_. `issue tracker`_.
Arm licensees may contact Arm directly via their partner managers. Arm licensees may contact Arm directly via their partner managers.
@ -327,8 +325,8 @@ Security advisories
.. _OP-TEE Secure OS: https://github.com/OP-TEE/optee_os .. _OP-TEE Secure OS: https://github.com/OP-TEE/optee_os
.. _NVIDIA Trusted Little Kernel: http://nv-tegra.nvidia.com/gitweb/?p=3rdparty/ote_partner/tlk.git;a=summary .. _NVIDIA Trusted Little Kernel: http://nv-tegra.nvidia.com/gitweb/?p=3rdparty/ote_partner/tlk.git;a=summary
.. _Trusty Secure OS: https://source.android.com/security/trusty .. _Trusty Secure OS: https://source.android.com/security/trusty
.. _GitHub: https://www.github.com/ARM-software/arm-trusted-firmware .. _trustedfirmware.org: https://git.trustedfirmware.org/TF-A/trusted-firmware-a.git
.. _GitHub issue tracker: https://github.com/ARM-software/tf-issues/issues .. _issue tracker: http://issues.trustedfirmware.org
.. _Security Center: ./docs/security-center.rst .. _Security Center: ./docs/security-center.rst
.. _license: ./license.rst .. _license: ./license.rst
.. _Contributing Guidelines: ./contributing.rst .. _Contributing Guidelines: ./contributing.rst