1Contributing Process
2====================
3
4Contributions to the TF-M project need to follow the process below.
5
6.. Note::
7
8   Please contact TF-M mailing list
9   `tf-m@lists.trustedfirmware.org <mailing_list_>`_ for any question.
10
11- It is recommended to subscribe to TF-M mailing list
12  via `this page <https://lists.trustedfirmware.org/mailman3/lists/tf-m.lists.trustedfirmware.org>`_.
13- Refer to the :doc:`/roadmap` or send a mail to the TF-M mailing list `tf-m@lists.trustedfirmware.org <mailing_list_>`_
14  to get the latest status and plan of TF-M.
15- Follow :doc:`Design Proposal Guideline </contributing/tfm_design_proposal_guideline>`
16  to propose your design.
17- Follow guidelines below to prepare the patch:
18
19  - Clone the TF-M code on your own machine from `TF-M git repository
20    <https://git.trustedfirmware.org/TF-M/trusted-firmware-m.git>`_.
21  - Follow the :doc:`TF-M getting started </getting_started/tfm_getting_started>`,
22    :doc:`Build Instructions </building/tfm_build_instruction>` and
23    :doc:`Coding Guide </contributing/coding_guide>` for the TF-M project.
24  - Make your changes in logical chunks to help reviewers. Each commit should
25    be a separate review and either work properly or be squashed after the
26    review and before merging.
27  - Follow :doc:`Documentation Contribution Guidelines </contributing/doc_guidelines>`
28    to update documentation in ``docs`` folder if needed.
29  - Test your changes and add details to the commit description.
30  - The code is accepted under :doc:`Developer Certificate of Origin (DCO) </contributing/dco>`.
31    Use ``git commit -s`` to add a ``Signed-off-by`` trailer at the end of the
32    commit log message.
33    See `git-commit <https://git-scm.com/docs/git-commit>`_ for details.
34  - Ensure that each changed file has the correct copyright and license
35    information. Files that entirely consist of contributions to this project
36    should have a copyright notice and BSD-3-Clause SPDX license identifier of
37    the form
38
39    ::
40
41        SPDX-License-Identifier: BSD-3-Clause
42        SPDX-FileCopyrightText: Copyright The TrustedFirmware-M Contributors
43
44    to reflect the community ownership of the project. Individual copyrights
45    can be traced back through the corresponding commits. For more details please refer
46    to `Linux Foundation guidelines on copyright notices`_ for OSS projects.
47    Patches that contain changes to imported Third Party IP files should retain
48    their original copyright and license notices. If changes are made to the imported
49    files, then add an additional ``SPDX-FileCopyrightText`` tag line as shown above.
50
51    The original form of the project copyright note as
52
53        Copyright (c) XXXX[-YYYY], <OWNER>. All rights reserved.
54
55    is still appropriate but shall be avoided in the new files.
56
57  - Add a `Change-Id <https://review.trustedfirmware.org/Documentation/user-changeid.html>`_
58    to the commit message, which can be generated any way you like (e.g. from
59    the SHA of the commit).
60    It is suggested to clone repositories with commit-msg hook. The commit-msg
61    hook attaches Change-Id automatically.
62    Take `trusted-firmware-m <https://review.trustedfirmware.org/admin/repos/TF-M/trusted-firmware-m>`_
63    as an example.
64
65- Submit your patch for review.
66  Refer to `Uploading Changes <https://review.trustedfirmware.org/Documentation/user-upload.html>`_
67  for details of uploading patch.
68- Add relevant :doc:`code owner(s) </contributing/maintainers>` for reviewing
69  the patch.
70- You may be asked to provide further details or make additional changes.
71- You can discuss further with code owner(s) and maintainer(s) directly via
72  TF-M mailing list `tf-m@lists.trustedfirmware.org <mailing_list_>`_ if necessary.
73- If multiple patches are linked in a chain then code owners and maintainers
74  should review and merge individual patches when they are ready, rather than
75  waiting for the entire chain to be reviewed. If multiple patches are intended
76  to be merged together then authors shall use topics or explicitly mention
77  that in the commit message.
78- Click ``Allow-CI +1`` button on Gerrit page to run CI to validate your patch.
79  Your patch shall pass CI successfully before being merged. Code owner(s) and
80  maintainer(s) may ask for additional test.
81- Once the change is approved by code owners, the patch will be merged by the
82  maintainer.
83
84--------------
85
86.. _mailing_list: tf-m@lists.trustedfirmware.org
87.. _Linux Foundation guidelines on copyright notices: https://www.linuxfoundation.org/blog/blog/copyright-notices-in-open-source-software-projects
88
89*Copyright (c) 2017-2022, Arm Limited. All rights reserved.*
90