andrius
/
arm-trusted-firmware
1
0
Fork 0
Code Issues Pull Requests Releases Wiki Activity

doc: Update contribution guidelines 

Update the documentation for trustedfirmware.org migration

Change-Id: Ibb7052b0becbec3326164f1503806ca2c2fd4dcc
Signed-off-by: Louis Mayencourt <louis.mayencourt@arm.com>
This commit is contained in:
Louis Mayencourt 2019-03-22 11:47:22 +00:00
parent 18ff0b61bb
commit 63fdda2d98
4 changed files with 117 additions and 129 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

107
contributing.rst
View File

@ -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)`_.
- 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 @@ 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/

110
docs/frequently-asked-questions.rst
View File

@ -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/

13
docs/user-guide.rst
View File

@ -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

16
readme.rst
View File

@ -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