1.. SPDX-License-Identifier: BSD-3-Clause
2.. SPDX-FileCopyrightText: Copyright TF-RMM Contributors.
3
4*******************
5Contributor's Guide
6*******************
7
8Getting Started
9===============
10
11-  Make sure you have a Github account and you are logged on
12   `review.trustedfirmware.org`_.
13
14-  Clone `RMM`_ on your own machine as described in
15   :ref:`getting_started_get_source`.
16
17-  If you plan to contribute a major piece of work, it is usually a good idea to
18   start a discussion around it on the mailing list. This gives everyone
19   visibility of what is coming up, you might learn that somebody else is
20   already working on something similar or the community might be able to
21   provide some early input to help shaping the design of the feature.
22
23-  If you intend to include Third Party IP in your contribution, please mention
24   it explicitly in the email thread and ensure that the changes that include
25   Third Party IP are made in a separate patch (or patch series).
26
27-  Create a local topic branch based on the `RMM`_ ``main`` branch.
28
29Making Changes
30==============
31
32-  See the `License and Copyright for Contributions`_ section for guidance
33   on license and copyright.
34
35-  Ensure commits adhere to the project's :ref:`Commit Style`.
36
37-  Make commits of logical units. See these general `Git guidelines`_ for
38   contributing to a project.
39
40-  Keep the commits on topic. If you need to fix another bug or make another
41   enhancement, please address it on a separate topic branch.
42
43-  Split the patch into manageable units. Small patches are usually easier to
44   review so this will speed up the review process.
45
46-  Avoid long commit series. If you do have a long series, consider whether
47   some commits should be squashed together or addressed in a separate topic.
48
49-  Follow the :ref:`Coding Standard`.
50
51-  Use the static checks as shown in :ref:`build_options_examples` to perform
52   checks like checkpatch, checkspdx, header files include order, clang-tidy,
53   cppcheck etc. A sample static analysis command line is given below, assuming
54   the tools have been setup as per instruction in :ref:`getting_started`.
55
56   .. code-block:: bash
57
58      cd $rmm_root
59      cmake -DRMM_CONFIG=fvp_defcfg -S . -B build -DRMM_TOOLCHAIN=llvm -DCMAKE_EXPORT_COMPILE_COMMANDS=ON
60      cmake --build build -- checkpatch checkspdx-patch checkincludes-patch clang-tidy-patch cppcheck-misra
61
62-  Where appropriate, please update the documentation.
63
64   -  Consider whether the :ref:`Design` document or other in-source
65      documentation needs updating.
66
67-  Ensure that each patch in the patch series compiles in all supported
68   configurations. For generic changes, such as on the libraries, The
69   :ref:`RMM Fake host architecture` should be able to, at least,
70   build. Patches which do not compile will not be merged.
71
72-  Please test your changes and add suitable tests in the available test
73   frameworks for any new functionality.
74
75Submitting Changes
76==================
77
78-  Assuming the clone of the repo has been done as mentioned in the
79   :ref:`getting_started_get_source` and *origin* refers to the upstream repo,
80   submit your changes for review targeting the ``integration`` branch.
81   Create a topic that describes the target of your changes to help group
82   related patches together.
83
84   .. code::
85
86       git push origin HEAD:refs/for/integration [-o topic=<your_topic>]
87
88   Refer to the `Gerrit Uploading Changes documentation`_ for more details.
89
90-  Add reviewers for your patch:
91
92   -  At least one maintainer. See the list of :ref:`maintainers`.
93
94   -  Alternatively, you might send an email to the `TF-RMM mailing list`_
95      to broadcast your review request to the community.
96
97-  The changes will then undergo further review by the designated people. Any
98   review comments will be made directly on your patch. This may require you to
99   do some rework. For controversial changes, the discussion might be moved to
100   the `TF-RMM mailing list`_ to involve more of the community.
101
102-  The patch submission rules are the following. For a patch to be approved
103   and merged in the tree, it must get a ``Code-Review+2``.
104
105   In addition to that, the patch must also get a ``Verified+1``. This is
106   usually set by the Continuous Integration (CI) bot when all automated tests
107   passed on the patch. Sometimes, some of these automated tests may fail for
108   reasons unrelated to the patch. In this case, the maintainers might
109   (after analysis of the failures) override the CI bot score to certify that
110   the patch has been correctly tested.
111
112   In the event where the CI system lacks proper tests for a patch, the patch
113   author or a reviewer might agree to perform additional manual tests
114   in their review and the reviewer incorporates the review of the additional
115   testing in the ``Code-Review+1`` to attest that the patch works as expected.
116
117-  When the changes are accepted, the :ref:`maintainers` will integrate them.
118
119   -  Typically, the :ref:`maintainers` will merge the changes into the
120      ``integration`` branch.
121
122   -  If the changes are not based on a sufficiently-recent commit, or if they
123      cannot be automatically rebased, then the :ref:`maintainers` may rebase it
124      on the ``integration`` branch or ask you to do so.
125
126   -  After final integration testing, the changes will make their way into the
127      ``main`` branch. If a problem is found during integration, the
128      :ref:`maintainers` will request your help to solve the issue. They may
129      revert your patches and ask you to resubmit a reworked version of them or
130      they may ask you to provide a fix-up patch.
131
132.. _copyright-license-guidance:
133
134License and Copyright for Contributions
135=======================================
136
137All new files should include the BSD-3-Clause SPDX license identifier
138where possible. When contributing code to us, the committer and all authors
139are required to make the submission under the terms of the
140:ref:`Developer Certificate of Origin`, confirming that the code submitted can
141(legally) become part of the project, and be subject to the same BSD-3-Clause
142license. This is done by including the standard Git ``Signed-off-by:``
143line in every commit message. If more than one person contributed to the
144commit, they should also add their own ``Signed-off-by:`` line.
145
146Files that entirely consist of contributions to this project should
147have a copyright notice and BSD-3-Clause SPDX license identifier of
148the form :
149
150.. code::
151
152   SPDX-License-Identifier: BSD-3-Clause
153   SPDX-FileCopyrightText: Copyright TF-RMM Contributors.
154
155Patches that contain changes to imported Third Party IP files should retain
156their original copyright and license notices. If changes are made to the
157imported files, then add an additional ``SPDX-FileCopyrightText`` tag line
158as shown above.
159
160--------------
161
162.. _review.trustedfirmware.org: https://review.trustedfirmware.org
163.. _RMM: https://git.trustedfirmware.org/TF-RMM/tf-rmm.git
164.. _Git guidelines: http://git-scm.com/book/ch5-2.html
165.. _Gerrit Uploading Changes documentation: https://review.trustedfirmware.org/Documentation/user-upload.html
166.. _TF-A Tests: https://trustedfirmware-a-tests.readthedocs.io
167.. _TF-RMM mailing list: https://lists.trustedfirmware.org/mailman3/lists/tf-rmm.lists.trustedfirmware.org/
168