diff options
| -rw-r--r-- | contributing.rst | 107 | ||||
| -rw-r--r-- | docs/frequently-asked-questions.rst | 116 | ||||
| -rw-r--r-- | docs/user-guide.rst | 13 | ||||
| -rw-r--r-- | readme.rst | 16 |
4 files changed, 120 insertions, 132 deletions
diff --git a/contributing.rst b/contributing.rst index d98d5b98..6c94d9ce 100644 --- a/contributing.rst +++ b/contributing.rst @@ -4,22 +4,18 @@ Contributing to Trusted Firmware-A 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 - everyone visibility of whether others are working on something similar. Arm - licensees may contact Arm directly via their partner managers instead if - they prefer. + everyone visibility of whether others are working on something similar. - - 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 raise a separate `issue`_ for this and ensure that the changes that include Third Party IP are made on a separate topic branch. -- `Fork`_ `arm-trusted-firmware`_ on GitHub. -- Clone the fork to your own machine. -- Create a local topic branch based on the `arm-trusted-firmware`_ ``master`` +- Clone `arm-trusted-firmware-a`_ on your own machine as suggested on the + `User Guide`_. +- Create a local topic branch based on the `arm-trusted-firmware-a`_ ``master`` branch. Making Changes @@ -27,12 +23,11 @@ Making Changes - Make commits of logical units. See these general `Git guidelines`_ for contributing to a project. -- Follow the `Linux coding style`_; this style is enforced for the TF-A - project (style errors only, not warnings). +- Follow the `Coding Guidelines`_. - Use the checkpatch.pl script provided with the Linux source tree. A - Makefile target is provided for convenience (see section 2 in the - `User Guide`_). + Makefile target is provided for convenience (see the "Checking source code + style" section in the `User Guide`_). - 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 @@ -40,14 +35,11 @@ Making Changes - 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. - Make sure your commit messages are in the proper format. If a commit fixes - a GitHub `issue`_, include a reference (e.g. - "fixes arm-software/tf-issues#45"); this ensures the `issue`_ is - `automatically closed`_ when merged into the `arm-trusted-firmware`_ ``master`` - branch. + an `issue`_, include a reference. - Where appropriate, please update the documentation. - - Consider whether the `User Guide`_, `Porting Guide`_, `Firmware Design`_ or - other in-source documentation needs updating. + - Consider whether the `User Guide`_, `Porting Guide`_, `Firmware Design`_ + or other in-source documentation needs updating. - Ensure that each changed file has the correct copyright and license information. Files that entirely consist of contributions to this 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, include the documentation changes within the single commit. -- Please test your changes. As a minimum, ensure UEFI boots to the shell on - the Foundation FVP. See `Running the software on FVP`_ for more information. +- Please test your changes. As a minimum, ensure that Linux boots on the + 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 ------------------ - 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 - ``Signed-off-by:`` and ``Author:`` lines must match. If anyone else contributes - to the commit, they must also add their own ``Signed-off-by:`` line. - By adding this line the contributor certifies the contribution is made 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. + ``Signed-off-by:`` and ``Author:`` lines must match. If anyone else + contributes to the commit, they must also add their own ``Signed-off-by:`` + line. By adding this line the contributor certifies the contribution is made + under the terms of the `Developer Certificate of Origin (DCO)`_. + + More details may be found in the `Gerrit Signed-off-by Lines guidelines`_. + +- 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. - - The changes in the `pull request`_ will then undergo further review and - testing by the `Maintainers`_. Any review comments will be made as - comments on the `pull request`_. 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. - - Typically, the `Maintainers`_ will merge the `pull request`_ into the - ``integration`` branch within the GitHub UI, creating a merge commit. - - Please avoid creating merge commits in the `pull request`_ itself. - - If the `pull request`_ is not based on a recent commit, the `Maintainers`_ - may rebase it onto the ``master`` branch first, or ask you to do this. - - If the `pull request`_ cannot be automatically merged, the `Maintainers`_ - will ask you to rebase it onto the ``master`` branch. - - After final integration testing, the `Maintainers`_ will push your merge - commit to the ``master`` branch. If a problem is found during integration, - 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 + - Typically, the `Maintainers`_ will merge the changes into the + ``integration`` branch. + - If the changes are not based on a sufficiently-recent commit, or if they + cannot be automatically rebased, then the `Maintainers`_ may rebase it on + the ``master`` branch or ask you to do so. + - After final integration testing, the changes will make their way into the + ``master`` branch. If a problem is found during integration, the merge + commit will be removed from the ``integration`` branch and the + `Maintainers`_ will ask you to create a new patch set to resolve the 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 -.. _issue: https://github.com/ARM-software/tf-issues/issues -.. _issue tracking repository: https://github.com/ARM-software/tf-issues -.. _Fork: https://help.github.com/articles/fork-a-repo -.. _arm-trusted-firmware: https://github.com/ARM-software/arm-trusted-firmware +.. _developer.trustedfirmware.org: https://developer.trustedfirmware.org +.. _issue: https://developer.trustedfirmware.org/project/board/1/ +.. _arm-trusted-firmware-a: https://git.trustedfirmware.org/TF-A/trusted-firmware-a.git .. _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 -.. _automatically closed: https://help.github.com/articles/closing-issues-via-commit-messages .. _Porting Guide: ./docs/porting-guide.rst .. _Firmware Design: ./docs/firmware-design.rst .. _license.rst: ./license.rst @@ -126,4 +124,7 @@ Submitting Changes .. _Maintainers: ./maintainers.rst .. _Running the software on FVP: ./docs/user-guide.rst#user-content-running-the-software-on-fvp .. _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/ diff --git a/docs/frequently-asked-questions.rst b/docs/frequently-asked-questions.rst index 7a4ff0ed..6aa04f0a 100644 --- a/docs/frequently-asked-questions.rst +++ b/docs/frequently-asked-questions.rst @@ -1,91 +1,79 @@ 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 -you push to the source topic branch of an open PR, the PR is automatically -updated with the new commits. +Often it is necessary to update your patch set before it is merged. Refer to the +`Gerrit Upload Patch Set documentation`_ on how to do so. -If you need to modify existing commits in the PR (for example following review -comments), then use the ``--force`` option when pushing. Any comments that apply -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. +If you need to modify an existing patch set with multiple commits, refer to the +`Gerrit Replace Changes documentation`_. -When the PR is finally merged, you will be given the option of deleting your -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? --------------------------------------------- +How long will my changes take to merge into ``integration``? +------------------------------------------------------------ This can vary a lot, depending on: -* How important the Pull Request (PR) is considered by the TF maintainers. Where - possible, you should indicate the required timescales for merging the PR and - the impact of any delay. +* How important the patch set is considered by the TF maintainers. Where + possible, you should indicate the required timescales for merging the patch + 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 - coding guidelines, have already had some code review, and have been - appropriately tested. Note that PRs from Arm engineers go through an internal - review process before appearing on GitHub, therefore may appear to be merged - more quickly. +* The quality of the patch set. Patches are likely to be merged more quickly if + they follow the coding guidelines, have already had some code review, and have + been appropriately tested. -* The impact of the PR. For example, a PR that changes a key generic API is - likely to receive much greater scrutiny than a local change to a specific - platform port. +* The impact of the patch set. For example, a patch that changes a key generic + API is likely to receive much greater scrutiny than a local change to a + specific platform port. * How much opportunity for external review is required. For example, the TF 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 feedback from specific parties. -* How many other topics need to be integrated and the risk of conflict between - the topics. +* How many other patch sets are waiting to be integrated and the risk of + conflict between the topics. -* Is there a code freeze in place in preparation for the release. Please refer - the `release information`_ for more details. +* If there is a code freeze in place in preparation for the release. Please + refer the `release information`_ for more details. * The workload of the TF maintainers. -Feel free to add a comment to your PR to get an estimate of when it will -be merged. - -How long will it take for my merged Pull Request to go from ``integration`` to ``master``? ------------------------------------------------------------------------------------------- +How long will it take for my changes to go from ``integration`` to ``master``? +------------------------------------------------------------------------------ -This depends on how many concurrent Pull Requests (PRs) 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 several things over the course of a few days, it might take up to a week. +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 +several things over the course of a few days, it might take up to a week. Typically, it will be 1-2 days. 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 -will be merged onto ``integration``, which will temporarily diverge from the -release branch. The ``integration`` branch will be rebased onto ``master`` after -the release, and then ``master`` will be fast-forwarded to ``integration`` 1-2 -days later. This whole process could take up 4 weeks. Please refer the `release -information`_ for code freeze dates. The TF maintainers will inform the PR owner -if this is going to happen. - -It is OK to create a PR based on commits that are only available in -``integration`` or another PR, rather than ``master``. There is a risk that the -dependency commits will change (for example due to PR rework or integration -problems). If this happens, the dependent PR will need reworking. - -What are these strange comments in my Pull Request? ---------------------------------------------------- - -For example, comments like "Can one of the admins verify this patch?" or "test -this please". These are associated with Arm's Continuous Integration -infrastructure and can be safely ignored. Those who are curious can see the -documentation for `this Jenkins plugin`_ for more details. +receiving patches that will not be merged into the release. In this case, the +patches will be merged onto ``integration``, which will temporarily diverge from +the release branch. The ``integration`` branch will be rebased onto ``master`` +after the release, and then ``master`` will be fast-forwarded to ``integration`` +1-2 days later. This whole process could take up 4 weeks. Please refer the +`release information`_ for code freeze dates. The TF maintainers will inform the +patch owner if this is going to happen. + +It is OK to create a patch based on commits that are only available in +``integration`` or another patch set, rather than ``master``. There is a risk +that the dependency commits will change (for example due to patch set rework or +integration problems). If this happens, the dependent patch will need reworking. + +What are these strange comments in my changes? +---------------------------------------------- + +All the comments from ``ci-bot-user`` are associated with Continuous Integration +infrastructure. The links published on the comment are not currently accessible, +but would be after the CI has been transitioned to `trustedfirmware.org`_. +Please refer to https://github.com/ARM-software/tf-issues/issues/681 for more +details on the timelines. .. _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/ diff --git a/docs/user-guide.rst b/docs/user-guide.rst index 0848769b..769ad450 100644 --- a/docs/user-guide.rst +++ b/docs/user-guide.rst @@ -81,11 +81,11 @@ In addition, the following optional packages and tools may be needed: Getting the TF-A source code ---------------------------- -Download the TF-A source code from Github: - -:: - - git clone https://github.com/ARM-software/arm-trusted-firmware.git +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 +commit messages. 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 .. _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 +.. _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 master tree: https://github.com/torvalds/linux/tree/master/ .. _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 .. _Secure Partition Manager Design guide: secure-partition-manager-design.rst .. _`Trusted Firmware-A Coding Guidelines`: coding-guidelines.rst - _`Library at ROM`: romlib-design.rst +.. _`Library at ROM`: romlib-design.rst @@ -251,15 +251,13 @@ Still to come - Ongoing security hardening, optimization and quality improvements. 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 --------------- -Get the TF-A source code from `GitHub`_. - -See the `User Guide`_ for instructions on how to install, build and use TF-A -with the Arm `FVP`_\ s. +See the `User Guide`_ for instructions on how to download, install, build and +use TF-A with the Arm `FVP`_\ s. See the `Firmware Design`_ for information on how TF-A works. @@ -281,7 +279,7 @@ IRC channel Development discussion takes place on the #trusted-firmware-a 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 ~~~~~~~~~~~~~~~~~~~~ @@ -289,7 +287,7 @@ Feedback and support 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 `Security Center`_. For all other feedback, please use the -`GitHub issue tracker`_. +`issue tracker`_. Arm licensees may contact Arm directly via their partner managers. @@ -326,8 +324,8 @@ Security advisories .. _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 .. _Trusty Secure OS: https://source.android.com/security/trusty -.. _GitHub: https://www.github.com/ARM-software/arm-trusted-firmware -.. _GitHub issue tracker: https://github.com/ARM-software/tf-issues/issues +.. _trustedfirmware.org: https://git.trustedfirmware.org/TF-A/trusted-firmware-a.git +.. _issue tracker: http://issues.trustedfirmware.org .. _Security Center: ./docs/security-center.rst .. _license: ./license.rst .. _Contributing Guidelines: ./contributing.rst |