doc: Update contribution guidelines
Update the documentation for trustedfirmware.org migration
Change-Id: Ibb7052b0becbec3326164f1503806ca2c2fd4dcc
Signed-off-by: Louis Mayencourt <louis.mayencourt@arm.com>
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/