Merge pull request #1918 from lmayencourt/lm/contrib_guidelines

doc: Update contribution guidelines

2 files changed, 59 insertions, 70 deletions

diff --git a/docs/frequently-asked-questions.rst b/docs/frequently-asked-questions.rst
index 7a4ff0ede..6aa04f0a8 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 0848769b3..769ad4505 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