Merge pull request #1918 from lmayencourt/lm/contrib_guidelines

doc: Update contribution guidelines

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/

docs/frequently-asked-questions.rst

 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/

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

readme.rst

@@ -252,15 +252,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.
 
@@ -282,7 +280,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
 ~~~~~~~~~~~~~~~~~~~~
@@ -290,7 +288,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.
 
@@ -327,8 +325,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