Merge pull request #1918 from lmayencourt/lm/contrib_guidelines
doc: Update contribution guidelines
diff --git a/contributing.rst b/contributing.rst
index d98d5b9..6c94d9c 100644
--- a/contributing.rst
+++ b/contributing.rst
@@ -4,22 +4,18 @@
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 @@
- 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 @@
- 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 @@
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)`_.
- - 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.
+ 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.
+
+ 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 @@
.. _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 7a4ff0e..6aa04f0 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 changes to go from ``integration`` to ``master``?
+------------------------------------------------------------------------------
-How long will it take for my merged Pull Request 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.
+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 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.
+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 Pull Request?
----------------------------------------------------
+What are these strange comments in my changes?
+----------------------------------------------
-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.
+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 0848769..769ad45 100644
--- a/docs/user-guide.rst
+++ b/docs/user-guide.rst
@@ -81,11 +81,11 @@
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 @@
.. _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 @@
.. _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
diff --git a/readme.rst b/readme.rst
index 6f47812..849bbb3 100644
--- a/readme.rst
+++ b/readme.rst
@@ -252,15 +252,13 @@
- 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 @@
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 @@
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 @@
.. _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