mirror of
https://github.com/CTCaer/switch-l4t-atf.git
synced 2024-11-24 10:20:00 +00:00
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
parent
18ff0b61bb
commit
63fdda2d98
107
contributing.rst
107
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)`_.
|
||||
|
||||
- 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/
|
||||
|
||||
@ -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/
|
||||
|
||||
@ -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
16
readme.rst
@ -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
|
||||
|
||||
Loading…
Reference in New Issue
Block a user