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