aboutsummaryrefslogtreecommitdiff
path: root/docs/contributing
diff options
context:
space:
mode:
Diffstat (limited to 'docs/contributing')
-rw-r--r--docs/contributing/code_review_guide.rst32
-rw-r--r--docs/contributing/coding_guide.rst8
-rw-r--r--docs/contributing/contributing_process.rst117
-rw-r--r--docs/contributing/dco.rst2
-rw-r--r--docs/contributing/doc_guidelines.rst74
-rw-r--r--docs/contributing/index.rst10
-rw-r--r--docs/contributing/lic.rst2
-rw-r--r--docs/contributing/maintainers.rst161
-rwxr-xr-xdocs/contributing/tfm_design_proposal_guideline.rst118
-rw-r--r--docs/contributing/tfm_design_proposal_process.rst156
10 files changed, 349 insertions, 331 deletions
diff --git a/docs/contributing/code_review_guide.rst b/docs/contributing/code_review_guide.rst
index 08d72a2832..5b260c2bdd 100644
--- a/docs/contributing/code_review_guide.rst
+++ b/docs/contributing/code_review_guide.rst
@@ -4,7 +4,7 @@ Code Review Guideline
The purpose of this document is to clarify design items to be reviewed during
the code review process.
-Please contact :doc:`maintainers </docs/contributing/maintainers>` or write an e-mail
+Please contact :doc:`maintainers </contributing/maintainers>` or write an e-mail
thread on the `TF-M mailing list <mailto:tf-m@lists.trustedfirmware.org>`_ for
any questions.
@@ -13,9 +13,9 @@ List of the guidelines
**********************
The prerequisites before going to the review stage:
-- Read the :doc:`Contributing Process </docs/contributing/contributing_process>`
+- Read the :doc:`Contributing Process </contributing/contributing_process>`
to know basic concepts.
-- Read the :doc:`Source Structure </docs/technical_references/design_docs/source_structure>`
+- Read the :ref:`source_structure`
for structure related reference.
The review guidelines consist of these items:
@@ -78,18 +78,14 @@ Examples:
.. code-block:: c
- /* R3.1 FILE: s/spm/ffm/psa_client.c */
+ /* R3.1 FILE: s/spm/core/psa_client.c */
- /* R3.2 FILE: s/spm/cmsis_psa/tfm_secure_context.c */
+ /* R3.2 FILE: s/spm/core/tfm_secure_context.c */
- /* R3.3 FILE: s/spm/cmsis_psa/main.c */
-
- /* R3.4 FILE: s/spm/cmsis_psa/main.c, 'main' is a good entry name. */
- void main(void);
- /* R3.4 FILE: s/spm/ffm/spm.c, 'spm\_' as the namespace */
+ /* R3.4 FILE: s/spm/core/spm.c, 'spm\_' as the namespace */
void spm_init(void);
- /* R3.5 FILE: s/spm/ffm/main.c */
+ /* R3.5 FILE: s/spm/core/main.c */
static void init_functions(void);
/* R3.6 Not permitted: */
@@ -105,7 +101,7 @@ Assembler code
external MACRO wrapped assembler code is allowed. Here is one example of the
logic folder:
- - 'secure_fw/spm/ffm'.
+ - 'secure_fw/spm'.
Examples:
@@ -113,7 +109,7 @@ Examples:
/*
* R4.1 The following MACRO is allowed to be referenced under
- * 'secure_fw/spm/ffm'
+ * 'secure_fw/spm'
*/
#define SVC(code) __asm volatile("svc %0", ::"I"(code))
@@ -210,11 +206,12 @@ TF-M has the requirements on commit message:
============== ====================================================
Topic Justification
============== ====================================================
-Boot bl2/*
+Boot `bl2/*` or `bl1/*`
Build For build system related purpose.
Docs All \*.rst changes.
Dualcpu Dual-cpu related changes.
HAL Generic HAL interface/implementation changes.
+Interface Interface changes, either Non-source and secure.
Pack For packing purpose.
Platform Generic platform related changes under `platform/*`.
Platform Name Specific platform changes.
@@ -222,8 +219,9 @@ Partition Multiple partition related changes.
Partition Name Specific partition related changes.
Service Multiple service related changes.
Service Name Specific service related changes.
-SPM secure_fw/spm/*
-SPRTL secure-fw/partitions/lib/sprt/*
+SPM `secure_fw/spm/*`
+SPRTL `secure-fw/partitions/lib/runtime/*`
+Tool `tools` folder or `tf-m-tools` repo
============== ====================================================
.. note::
@@ -234,4 +232,4 @@ SPRTL secure-fw/partitions/lib/sprt/*
--------------
-*Copyright (c) 2020-2021, Arm Limited. All rights reserved.*
+*Copyright (c) 2020-2022, Arm Limited. All rights reserved.*
diff --git a/docs/contributing/coding_guide.rst b/docs/contributing/coding_guide.rst
index f208fc0944..e9f46f912b 100644
--- a/docs/contributing/coding_guide.rst
+++ b/docs/contributing/coding_guide.rst
@@ -18,13 +18,13 @@ remain within clear scope.
The guidance below is provided as a help. It isn't meant to be a definitive
list.
-As implied in the :doc:`contributing guide </docs/contributing/contributing_process>`
+As implied in the :doc:`contributing guide </contributing/contributing_process>`
maintainers have the right to decide on what's acceptable in case of any
divergence.
.. Warning::
- Text files do not fall within these rules as they may require different formatting.``
+ Text files do not fall within these rules as they may require different formatting.
****************
Consistent style
@@ -47,7 +47,7 @@ List of rules
- Use void argument if your function doesn't contain any argument.
- Use C90 ``/* */`` for comments rather than C99 ``//``
- No trailing spaces in code.
-- Max 80 characters length. Text files are exception as stated above.
+- Keep up to 100 characters per line but 140 chars can be accepted exceptionally.
- Open curly brace ``{`` at the same if/else/while/for/switch statement line.
- Use curly braces ``{ }`` for one line statement bodies also.
- Put open curly brace in the line below the function header.
@@ -76,4 +76,4 @@ List of rules
--------------
-*Copyright (c) 2018-2021, Arm Limited. All rights reserved.*
+*Copyright (c) 2018-2022, Arm Limited. All rights reserved.*
diff --git a/docs/contributing/contributing_process.rst b/docs/contributing/contributing_process.rst
index 8bd7e52281..b959868619 100644
--- a/docs/contributing/contributing_process.rst
+++ b/docs/contributing/contributing_process.rst
@@ -5,76 +5,79 @@ Contributions to the TF-M project need to follow the process below.
.. Note::
- Please contact :doc:`maintainers </docs/contributing/maintainers>` for any
- questions.
+ Please contact `TF-M mailing list <mailing_list_>`_ for any question.
-- Subscribe to `TF-M development
- <https://lists.trustedfirmware.org/mailman/listinfo/tf-m>`_ if not subscribed
- already.
+- It is recommended to subscribe to `TF-M mailing list <mailing_list_>`_
+ via `this page <https://lists.trustedfirmware.org/mailman3/lists/tf-m.lists.trustedfirmware.org>`_.
- Refer to the `Roadmap
<https://developer.trustedfirmware.org/w/tf_m/planning>`_ or send a mail to
- the tf-m@lists.trustedfirmware.org to check if this work is already
- planned/progresses elsewhere.
-- Create a task in `Phabricator
- <https://developer.trustedfirmware.org/maniphest>`_, put as many details as
- possible in the description. Add 'Trusted Firmware M' in the 'Tags' field.
-- For non-trivial changes, need to follow the design proposal process
- :doc:`Design Proposal Process </docs/contributing/tfm_design_proposal_process>`
- for the TF-M project.
-- After the design has been accepted by the maintainer(s), a corresponding
- patch should be posted; follow guidelines below:
+ the `TF-M mailing list <mailing_list_>`_ to get the latest status and plan of
+ TF-M.
+- Follow :doc:`Design Proposal Guideline </contributing/tfm_design_proposal_guideline>`
+ to propose your design.
+- Follow guidelines below to prepare the patch:
- Clone the TF-M code on your own machine from `TF-M git repository
<https://git.trustedfirmware.org/TF-M/trusted-firmware-m.git>`_.
- - Follow the :doc:`TF-M getting started </docs/getting_started/tfm_getting_started>`,
- :doc:`Build Instructions </docs/technical_references/instructions/tfm_build_instruction>` and
- :doc:`Coding Guide </docs/contributing/coding_guide>` for the TF-M project.
+ - Follow the :doc:`TF-M getting started </getting_started/tfm_getting_started>`,
+ :doc:`Build Instructions </building/tfm_build_instruction>`
+ :doc:`Coding Guide </contributing/coding_guide>` for the TF-M project.
- Make your changes in logical chunks to help reviewers. Each commit should
be a separate review and either work properly or be squashed after the
review and before merging.
- - Update documentation in docs/ folder if needed.
+ - Follow :doc:`Documentation Contribution Guidelines </contributing/doc_guidelines>`
+ to update documentation in ``docs`` folder if needed.
- Test your changes and add details to the commit description.
- - The code is accepted under :doc:`DCO </docs/contributing/dco>`, Developer
- Certificate of Origin, so you must add following fields to your
- commit description:
-
- .. code-block:: text
-
- Author: Full Name <email address>
- Signed-off-by: Full Name <email address>
-
- .. Note::
-
- Sign off authority needs to adhere to the [DCO](./dco.txt) rules.
-
- - You must add a `Change-Id
- <https://review.trustedfirmware.org/Documentation/user-changeid.html>` to
- the commit message, which can be generated any way you like (e.g. from the
- SHA of the commit), or use the commit hook.
- - Create a user in the `TF-M Gerrit <https://review.trustedfirmware.org>`,
- then add `SSH keys or HTTP credentials
- <https://review.trustedfirmware.org/settings/>`.
- - Submit your patch for review.
-
- .. code-block:: shell
-
- git push ssh://review.trustedfirmware.org:29418/TF-M/trusted-firmware-m.git HEAD:refs/for/master
-
- or
-
- .. code-block:: shell
-
- git push https://review.trustedfirmware.org/TF-M/trusted-firmware-m.git HEAD:refs/for/master
-
-- Add relevant :doc:`maintainers </docs/contributing/maintainers>` for reviewing
+ - The code is accepted under :doc:`Developer Certificate of Origin (DCO) </contributing/dco>`.
+ Use ``git commit -s`` to add a ``Signed-off-by`` trailer at the end of the
+ commit log message.
+ See `git-commit <https://git-scm.com/docs/git-commit>`_ for details.
+ - 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 identifier of
+ the form as shown in :doc:`lic`. Files that contain changes to imported
+ Third Party IP files should retain their original copyright and license
+ notices.
+
+ Contributors can add the following copyright note, (whilst) it is suggested
+ to update copyright note only for *major*, non-trivial changes.
+
+ ::
+
+ Copyright (c) XXXX[-YYYY], <OWNER>. All rights reserved.
+
+ where XXXX is the year of first contribution and YYYY is the optional year
+ of most recent contribution. <OWNER> is your or your company name.
+
+ - Add a `Change-Id <https://review.trustedfirmware.org/Documentation/user-changeid.html>`_
+ to the commit message, which can be generated any way you like (e.g. from
+ the SHA of the commit).
+ It is suggested to clone repositories with commit-msg hook. The commit-msg
+ hook attaches Change-Id automatically.
+ Take `trusted-firmware-m <https://review.trustedfirmware.org/admin/repos/TF-M/trusted-firmware-m>`_
+ as an example.
+
+- Submit your patch for review.
+ Refer to `Uploading Changes <https://review.trustedfirmware.org/Documentation/user-upload.html>`_
+ for details of uploading patch.
+- Add relevant :doc:`code owner(s) </contributing/maintainers>` for reviewing
the patch.
- You may be asked to provide further details or make additional changes.
-- You can discuss further with maintainer(s) by directly over email if
- necessary.
-- Once the change is approved by maintainers, the patch will be merged by the
+- You can discuss further with code owner(s) and maintainer(s) directly via
+ `TF-M mailing list <mailing_list_>`_ if necessary.
+- If multiple patches are linked in a chain then code owners and maintainers
+ should review and merge individual patches when they are ready, rather than
+ waiting for the entire chain to be reviewed. If multiple patches are intended
+ to be merged together then authors shall use topics or explicitly mention
+ that in the commit message.
+- Click ``Allow-CI +1`` button on Gerrit page to run CI to validate your patch.
+ Your patch shall pass CI successfully before being merged. Code owner(s) and
+ maintainer(s) may ask for additional test.
+- Once the change is approved by code owners, the patch will be merged by the
maintainer.
-- Mark the task as 'resolved' after patch is merged.
+
+.. _mailing_list: tf-m@lists.trustedfirmware.org
--------------
-*Copyright (c) 2017-2021, Arm Limited. All rights reserved.*
+*Copyright (c) 2017-2022, Arm Limited. All rights reserved.*
diff --git a/docs/contributing/dco.rst b/docs/contributing/dco.rst
index 7a5a4c3255..b8383479bb 100644
--- a/docs/contributing/dco.rst
+++ b/docs/contributing/dco.rst
@@ -3,7 +3,7 @@
Developer Certificate of Origin
###############################
-.. include:: /dco.txt
+.. include:: ../../dco.txt
:literal:
diff --git a/docs/contributing/doc_guidelines.rst b/docs/contributing/doc_guidelines.rst
index 607097de80..9dea2f38f8 100644
--- a/docs/contributing/doc_guidelines.rst
+++ b/docs/contributing/doc_guidelines.rst
@@ -2,7 +2,7 @@
Documentation Contribution Guidelines
#####################################
-The Trusted Firmware-M project uses `Sphinx`_ to generated the Official
+The Trusted Firmware-M project uses `Sphinx`_ to generate the Official
Documentation from `Restructed Text`_ `.rst` source files,
The aim is to align as much as possible with the official
@@ -20,7 +20,7 @@ The following short-list provides a quick summary of the rules.
- If the patch modifies a present file, the file's style should be followed
- If creating a new file,
- :doc:`integration guide </docs/integration_guide/tfm_integration_guide>` can be used as a reference.
+ :doc:`integration guide </integration_guide/index>` can be used as a reference.
- When a new style is to be expressed, consult the `Python Documentation Guidelines`_
*************
@@ -54,30 +54,19 @@ The following rules should be considered:
#. New introduced terms and abbreviations should be added to Glossary and
directly linked by the `:term:` notation across all documents using it.
-
**********************
Platform Documentation
**********************
The Documentation Build system provides an interface with the platform directory
-allowing maintainers to bundle platform specific documentation. **This behaviour
-needs to be explicitly enabled for each platform's space** by
-modifying the `platform/ext/index.rst` (responsible for generating the
-:doc:`Platform Index File </platform/ext/index>`) and adding a table of
-contents entry for the corresponding platform space.
-
+allowing maintainers to bundle platform specific documentation. Platforms are
+grouped by vendor. **This behaviour needs to be explicitly enabled for each
+vendor's space** by providing the `<vendor>/index.rst` (responsible for generating the
+:doc:`Platform Index File </platform/index>`) and adding a table of
+contents entry for the corresponding vendor's space.
The format and structure of this entry is not strictly defined, and allows
-flexible control of the platform's documentation space. In most cases it can be
-set to recursively match all documents under that directory.
-
-.. code-block:: restructuredtext
-
- .. toctree::
- :maxdepth: 4
- :caption: PLATFORM_X_CAPTION
- :glob:
-
- target/PLATFORM_X/**
+flexible control of vendor's and platform's documentation space.
+Follow the :ref:`platform_documentation` document for more details.
****************
Common Use Cases
@@ -89,7 +78,6 @@ for most common documentation elements.
Headers
=======
-
.. code-block:: restructuredtext
###################
@@ -97,7 +85,7 @@ Headers
###################
******************
- Chapter Ttitle(H2)
+ Chapter Title (H2)
******************
Chapter Section (H3)
@@ -112,7 +100,6 @@ Headers
Code Blocks
===========
-
The recommendation for code content, is to use the explicit code-block directive,
ideally with a defined lexer for the language the block contains.
@@ -186,8 +173,8 @@ will not be added to the index (So it cannot be referenced if needed)
+--------------+--------------+-------------+
Other types of tables such as list-tables and csv-tables are also permitted, as
-seen on :doc:`/docs/getting_started/tfm_getting_started` and
-:doc:`/docs/releases/1.0`
+seen on :doc:`/getting_started/tfm_getting_started` and
+:doc:`/releases/1.0`
External Links
@@ -228,7 +215,6 @@ labels, internal linking is the recommended approach.
*Copyright (c) XYZ *
-
Document Links
==============
@@ -236,10 +222,31 @@ A document included in the documentation can be referenced by the `doc:` notatio
.. code-block:: restructuredtext
- :doc:`integration guide </docs/integration_guide/tfm_integration_guide>`
+ :doc:`integration guide </integration_guide/tfm_integration_guide>`
The path is relative to the root of the Trusted Firmware-M code.
+Trusted Firmware-M project is spread among multiple repositories: Trusted Firmware-M, TF-M Tests,
+TF-M Tools and TF-M Extras. Every repository has its own documentation, and since
+:doc:`v2.0.0<../releases/2.0.0>`, they can be found under `Links`.
+
+Using `Intersphinx`_, it is now possible to use cross-reference roles from Sphinx to reference
+documentation from different projects (repositories), like TF-M Tests. Referencing documentation
+using the `doc:` notation is preferred and helps to avoid broken cross-references if the link of
+the document changes.
+
+For example, to get this: :doc:`Adding TF-M Regression Test Suite
+<TF-M-Tests:tfm_test_suites_addition>`; the Restructed Text would look like this:
+
+.. code-block:: restructuredtext
+
+ :doc:`Adding TF-M Regression Test Suite <TF-M-Tests:tfm_test_suites_addition>`
+
+As can be seen, it is quite similar to cross-referencing in Sphinx, except the path to the document
+is preceded with the external project name. For TF-M Tests, it is ``TF-M-Tests``. The names of
+other projects configured to be referenced using `Intersphinx`_ can be seen in the `conf.py`_ file
+under ``intersphinx_mapping``.
+
Reference specific section of a document
========================================
@@ -255,15 +262,13 @@ document. This technique can be used to add complex table in the bottom of a
document and create clickable quick access references to it for improved user
experience.
-
Glossary term
=============
For technical terms and abbreviations, the recommended guidance is to add an
-entry to the :doc:`/docs/glossary` and refer to it, using the `term:`
+entry to the :doc:`/glossary` and refer to it, using the `term:`
directive
-
.. code-block:: restructuredtext
HAL
@@ -289,12 +294,15 @@ References
#. `Restructed Text`_
#. `Python Documentation Guidelines`_
#. `Pygments Lexers`_
+#. `Intersphinx`_
.. _Sphinx: https://www.sphinx-doc.org/en/master/
.. _Restructed Text: https://docutils.sourceforge.io/rst.html
-.. _Python Documentation Guidelines: https://devguide.python.org/documenting/#style-guide
-.. _Pygments Lexers: https://pygments.org/docs/lexers/
+.. _Python Documentation Guidelines: https://devguide.python.org/documentation/style-guide/
+.. _Pygments Lexers: https://pygments.org/docs/api/#lexers
+.. _Intersphinx: https://www.sphinx-doc.org/en/master/usage/extensions/intersphinx.html
+.. _conf.py: https://git.trustedfirmware.org/TF-M/trusted-firmware-m.git/tree/docs/conf.py
--------------
-*Copyright (c) 2020-2021, Arm Limited. All rights reserved.*
+*Copyright (c) 2020-2023, Arm Limited. All rights reserved.*
diff --git a/docs/contributing/index.rst b/docs/contributing/index.rst
index e5f9c66be6..71ba543f9a 100644
--- a/docs/contributing/index.rst
+++ b/docs/contributing/index.rst
@@ -3,10 +3,14 @@ Contribution Guidelines
.. toctree::
:maxdepth: 1
- :glob:
-
- *
+ :titlesonly:
+ The process <contributing_process>
+ Code review <code_review_guide>
+ Maintainers and Owners <maintainers>
+ coding_guide
+ Documentation <doc_guidelines>
+ Design proposal <tfm_design_proposal_guideline>
--------------
diff --git a/docs/contributing/lic.rst b/docs/contributing/lic.rst
index b8d4ce520a..2beec6303a 100644
--- a/docs/contributing/lic.rst
+++ b/docs/contributing/lic.rst
@@ -3,7 +3,7 @@
License
#######
-.. include:: /license.rst
+.. include:: ../../license.rst
-----------
diff --git a/docs/contributing/maintainers.rst b/docs/contributing/maintainers.rst
index 6120dd8027..2b9ac6120a 100644
--- a/docs/contributing/maintainers.rst
+++ b/docs/contributing/maintainers.rst
@@ -15,28 +15,42 @@ Anton Komlev
:email: `Anton.Komlev@arm.com <Anton.Komlev@arm.com>`__
:github: `Anton-TF <https://github.com/Anton-TF>`__
+Antonio de Angelis
+ :email: `Antonio.deAngelis@arm.com <Antonio.deAngelis@arm.com>`__
+ :github: `adeaarm <https://github.com/adeaarm>`__
+
Chris Brand
:email: `Chris.Brand@cypress.com <chris.brand@cypress.com>`__
:github: `UEWBot <https://github.com/UEWBot>`__
-Ken Liu
- :email: `Ken.Liu@arm.com <Ken.Liu@arm.com>`__
- :github: `KenLSoft <https://github.com/KenLSoft>`__
-
David Hu
:email: `David.Hu@arm.com <David.Hu@arm.com>`__
:github: `davidhuziji <https://github.com/davidhuziji>`__
+Ken Liu
+ :email: `Ken.Liu@arm.com <Ken.Liu@arm.com>`__
+ :github: `KenLSoft <https://github.com/KenLSoft>`__
Code owners
===========
-Bootloader
-~~~~~~~~~~
+Bootloader and FWU
+~~~~~~~~~~~~~~~~~~
Tamas Ban
:email: `Tamas.Ban@arm.com <Tamas.Ban@arm.com>`__
- :github: `tamban01 <https://github.com/tamban01>`__
+ :github: `tamasban <https://github.com/tamasban>`__
+
+Sherry Zhang
+ :email: `Sherry.Zhang2@arm.com <Sherry.Zhang2@arm.com>`__
+ :github: `sherryzhang <https://github.com/sherryzhang>`__
+
+BL1 immutable bootloader
+~~~~~~~~~~~~~~~~~~~~~~~~
+
+Raef Coles
+ :email: `Raef.Coles@arm.com <Raef.Coles@arm.com>`__
+ :github: `RcColes <https://github.com/RcColes>`__
Secure Storage
~~~~~~~~~~~~~~
@@ -45,62 +59,99 @@ Jamie Fox
:email: `jamie.fox@arm.com <jamie.fox@arm.com>`__
:github: `jf549 <https://github.com/jf549>`__
+Sherry Zhang
+ :email: `Sherry.Zhang2@arm.com <Sherry.Zhang2@arm.com>`__
+ :github: `sherryzhang <https://github.com/sherryzhang>`__
+
Crypto
~~~~~~
-Soby Mathew
- :email: `Soby.Mathew@arm.com <Soby.Mathew@arm.com>`__
- :github: `soby-mathew <https://github.com/soby-mathew>`__
+Antonio de Angelis
+ :email: `Antonio.deAngelis@arm.com <Antonio.deAngelis@arm.com>`__
+ :github: `adeaarm <https://github.com/adeaarm>`__
-SPM & IPC
-~~~~~~~~~
+Summer Qin
+ :email: `Summer.Qin@arm.com <Summer.Qin@arm.com>`__
+ :github: `Summer-ARM <https://github.com/Summer-ARM>`__
+
+Framework (SPM, etc.)
+~~~~~~~~~~~~~~~~~~~~~
Ken Liu
:email: `Ken.Liu@arm.com <Ken.Liu@arm.com>`__
:github: `KenLSoft <https://github.com/KenLSoft>`__
-Mate Toth-Pal
- :email: `Mate.Toth-Pal@arm.com <Mate.Toth-Pal@arm.com>`__
- :github: `matetothpal <https://github.com/matetothpal>`__
-
-Audit Log
-~~~~~~~~~
-
-Jamie Fox
- :email: `jamie.fox@arm.com <jamie.fox@arm.com>`__
- :github: `jf549 <https://github.com/jf549>`__
+Kevin Peng
+ :email: `Kevin.Peng@arm.com <Kevin.Peng@arm.com>`__
+ :github: `kevin-peng-hao <https://github.com/kevin-peng-hao>`__
Attestation
~~~~~~~~~~~
-Tamas Ban
- :email: `Tamas.Ban@arm.com <Tamas.Ban@arm.com>`__
- :github: `tamban01 <https://github.com/tamban01>`__
+Maulik Patel
+ :email: `Maulik.Patel@arm.com <Maulik.Patel@arm.com>`__
+ :github: `maulik-arm <https://github.com/maulik-arm>`__
-CMake Build System
-~~~~~~~~~~~~~~~~~~
+David Hu
+ :email: `David.Hu@arm.com <David.Hu@arm.com>`__
+ :github: `davidhuziji <https://github.com/davidhuziji>`__
+
+Build System
+~~~~~~~~~~~~
+
+Raef Coles
+ :email: `Raef.Coles@arm.com <Raef.Coles@arm.com>`__
+ :github: `RcColes <https://github.com/RcColes>`__
Anton Komlev
:email: `Anton.Komlev@arm.com <Anton.Komlev@arm.com>`__
:github: `Anton-TF <https://github.com/Anton-TF>`__
+Tests
+~~~~~
+
+David Hu
+ :email: `David.Hu@arm.com <David.Hu@arm.com>`__
+ :github: `davidhuziji <https://github.com/davidhuziji>`__
+
+Kevin Peng
+ :email: `Kevin.Peng@arm.com <Kevin.Peng@arm.com>`__
+ :github: `kevin-peng-hao <https://github.com/kevin-peng-hao>`__
+
+
+Arm Platforms
+~~~~~~~~~~~~~
+
+MPS2, MPS3, MPS4, Musca(B1,S1)
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+David Hazi
+ :email: `David.Hazi@arm.com <david.hazi@arm.com>`__
+ :github: `david-hazi-arm <https://github.com/david-hazi-arm>`__
+
+Corstone1000
+^^^^^^^^^^^^
-Arm Platforms: MPS2, MPS3, Musca(A,B1,S1)
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Xueliang Zhong
+ :email: `Xueliang.Zhong@arm.com <xueliang.zhong@arm.com>`__
+ :github: `xueliang-zhong <https://github.com/xueliang-zhong-arm>`__
-Mark Horvath
- :email: `Mark.Horvath@arm.com <mark.horvath@arm.com>`__
- :github: `mark-horvath-arm <https://github.com/mark-horvath-arm>`__
+Emekcan Aras
+ :email: `Emekcan.Aras@arm.com <emekcan.aras@arm.com>`__
+ :github: `ememarar <https://github.com/ememarar>`__
-Lakshmi Kailasanathan
- :email: `Lakshmi.Kailasanathan@arm.com <lakshmi.kailasanathan@arm.com>`__
- :github: `lakkai <https://github.com/lakkai>`__
+RSE
+^^^
+
+Jamie Fox
+ :email: `jamie.fox@arm.com <jamie.fox@arm.com>`__
+ :github: `jf549 <https://github.com/jf549>`__
NXP Platforms
~~~~~~~~~~~~~
Andrej Butok
- :email: `Andrej.Butok@nxp.com <andrey.butok@nxp.com>`__
+ :email: `Andrey.Butok@nxp.com <andrey.butok@nxp.com>`__
:github: `AndreyButokNXP <https://github.com/AndreyButokNXP>`__
STM Platforms: DISCO_L562QE, NUCLEO_L552ZE_Q
@@ -118,35 +169,19 @@ Chris Brand
:email: `Chris Brand@cypress.com <chris.brand@cypress.com>`__
:github: `UEWBot <https://github.com/UEWBot>`__
-Raymond Ngun
- :email: `Raymond.Ngunn@cypress.com <raymond.ngunn@cypress.com>`__
- :github: `RaymondNgun <https://github.com/RaymondNgun>`__
-
Laird Connectivity Platforms:
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-Jamie McCrae
- :email: `Jamie.McCrae@lairdconnect.com <jamie.mccrae@lairdconnect.com>`__
- :github: `thedjnk <https://github.com/thedjnk>`__
+Greg Leach
+ :email: `Greg.Leach@lairdconnect.com <greg.leach@lairdconnect.com>`__
+ :github: `greg-leach <https://github.com/greg-leach>`__
Nordic Semiconductor Platforms
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-Ioannis Glaropoulos
- :email: `ioannis.glaropoulos@nordicsemi.no <ioannis.glaropoulos@nordicsemi.no>`__
- :github: `ioannisg <https://github.com/ioannisg>`__
-
-Andrzej Głąbek
- :email: `andrzej.glabek@nordicsemi.no <andrzej.glabek@nordicsemi.no>`__
- :github: `anangl <https://github.com/anangl>`__
-
-Øyvind Rønningstad
- :email: `oyvind.ronningstad@nordicsemi.no <oyvind.ronningstad@nordicsemi.no>`__
- :github: `oyvindronningstad <https://github.com/oyvindronningstad>`__
-
-Sebastian Bøe
- :email: `sebastian.boe@nordicsemi.no <sebastian.boe@nordicsemi.no>`__
- :github: `SebastianBoe <https://github.com/SebastianBoe>`__
+Georgios Vasilakis
+ :email: `georgios.vasilakis@nordicsemi.no <georgios.vasilakis@nordicsemi.no>`__
+ :github: `Vge0rge <https://github.com/Vge0rge>`__
Nuvoton Platform:
@@ -156,6 +191,14 @@ WS Chang
:email: `MS20 WSChang0@nuvoton.com <wschang0@nuvoton.com>`__
:github: `wschang0 <https://github.com/wschang0>`__
+
+ArmChina Platform:
+~~~~~~~~~~~~~~~~~~
+
+Jidong Mei
+ :email: `Jidong.Mei@armchina.com <Jidong.Mei@armchina.com>`__
+ :github: `JidongMei <https://github.com/JidongMei>`__
+
=============
-*Copyright (c) 2017-2020, Arm Limited. All rights reserved.*
+*Copyright (c) 2017-2024, Arm Limited. All rights reserved.*
diff --git a/docs/contributing/tfm_design_proposal_guideline.rst b/docs/contributing/tfm_design_proposal_guideline.rst
new file mode 100755
index 0000000000..9e7dfa0fcd
--- /dev/null
+++ b/docs/contributing/tfm_design_proposal_guideline.rst
@@ -0,0 +1,118 @@
+#########################
+Design proposal guideline
+#########################
+
+The design proposal guideline specifies the steps to propose and upload design
+proposals to TF-M. Those steps are lightweight and flexible to make sure that
+contributors can focus more on actual code implementation and iteration.
+
+The guideline encourages developers to share design proposal via
+TF-M mailing list [1]_ and TF-M technical forum (tech forum) [2]_.
+The design details can be discussed via code reviews of actual implementations.
+
+Typical steps are shown as the diagram below.
+
+.. uml::
+
+ @startuml
+
+ title Design proposal process
+
+ [*] --> propose : Non-trivial changes
+
+ state "Propose general ideas" as propose {
+ state "TF-M mailing list" as mail_list : Contributors send emails to mailing list\nto describe the design.
+ state "TF-M tech forum" as tech_forum : Contributors present the design\nin tech forum.
+
+ [*] --> mail_list
+ [*] --> tech_forum
+ }
+
+ note bottom of propose : Optional but strongly recommended
+
+ [*] --> upload
+ note right of upload : No prerequisites
+ propose --> upload
+
+ state "Upstream changes" as upload : Contributors upstream code patch\nand integration guide to gerrit.
+ state "Code review" as review : Reviewer review changes of\ncode and documents.\nChanges pass verifications.
+ state "Broadcast patches" as broadcast : Contributors ask for review\nin mailing list.
+ state "Approve and merge" as approve : Code owners approve changes.\nMaintainers merge patches.
+
+ upload --> broadcast : Optional
+ upload --> review
+
+ broadcast --> review
+ review --> review : Update implementation
+ review --> approve
+ approve --> [*]
+
+ @enduml
+
+Discussion in TF-M mailing list and tech forum
+==============================================
+
+It is **highly recommended** to propose and discuss designs in TF-M mailing list
+or TF-M tech forum, before or while the code implementation is under review.
+
+It is efficient and flexible to directly discuss design proposal via TF-M
+mailing list and TF-M tech forum. Contributors can receive quick and broad
+feedback from TF-M community.
+
+Although it is optional to present the ideas in mailing list or tech forum, it
+will help reviewers understand the design much better and expedite the code
+review process.
+
+Code review of details
+======================
+
+It is straightforward and convenient for contributors and reviewers to
+deliberate over design and implementation details via code review.
+
+Contributors can implement their design proposal and upstream the patch set to
+TF-M gerrit [3]_ for code review.
+For non-trivial changes or new major features, it is **strongly suggested** to
+propose the design to TF-M mailing list and tech forum in advance.
+
+Contributors don't have to wait for any approvals before upstreaming patches,
+even if the changes are non-trivial.
+No formal design document in advance is required anymore.
+
+The review process is the same as the general one [4]_, with some specific
+requirements:
+
+ - Contributors can send an email to TF-M mailing list to ask for review.
+ - If it requires additional reviewers besides code owners and maintainers,
+ contributors shall add the specific reviewers in the review list.
+ - Authors shall clearly specify the design purpose and briefly describe the
+ implementation in the commit message.
+ - Authors shall put essential comments and notes in code for the code changes.
+
+Code owners and maintainers may require contributors to further verify the
+implementation besides normal per-patch CI test. Contributors shall provide the
+verification results as requested.
+
+Integration guide and manual
+============================
+
+Contributors can create an integration guide or a user manual to describe how to
+integrate the new features related to the design proposal.
+
+Contributors shall update the corresponding documents if the design changes
+existing implementation.
+
+*********
+Reference
+*********
+
+.. [1] `TF-M mailing list <https://lists.trustedfirmware.org/mailman3/lists/tf-m.lists.trustedfirmware.org/>`_
+
+.. [2] `TF-M technical forum <https://www.trustedfirmware.org/meetings/tf-m-technical-forum/>`_
+
+.. [3] `TF-M gerrit <https://review.trustedfirmware.org/q/project:TF-M/trusted-firmware-m>`_
+
+.. [4] :doc:`Contributing process </contributing/contributing_process>`
+
+-------------------
+
+*Copyright (c) 2022, Arm Limited. All rights reserved.*
diff --git a/docs/contributing/tfm_design_proposal_process.rst b/docs/contributing/tfm_design_proposal_process.rst
deleted file mode 100644
index 0c10b7bcea..0000000000
--- a/docs/contributing/tfm_design_proposal_process.rst
+++ /dev/null
@@ -1,156 +0,0 @@
-Design proposal process
-=======================
-
-:Author: Gyorgy Szing
-:Organisation: Arm Limited
-:Contact: Gyorgy Szing <gyorgy.szing@arm.com>
-
-Purpose and Content
--------------------
-This document describes the steps of adding/changing Trusted Firmware design. It
-specifies:
-
- - The documentation format to be used.
- - The information which shall be captured.
- - The steps of the process.
- - The location where the information shall be captured during the process.
-
-General
--------
-The Trusted Firmware project uses the
-`reStructuredText <http://docutils.sourceforge.net/rst.html>`_ format with
-`Sphinx <http://www.sphinx-doc.org/en/master/usage/restructuredtext/index.html>`_
-extensions for documentation. Design documents shall be captured in this format.
-
-Design documents are kept under version control at the project's
-`Gerrit server <https://review.trustedfirmware.org>`_. All decisions made and
-important information gathered during the design discussion, which is not part
-of the design document shall be captured as Gerrit comments or notes for
-archiving purposes. To meet this requirement this process encourages the use of
-the Gerrit web UI for communication.
-
-
-Status of a document
----------------------
-The status of the document is captured in a *reST filed* called *Status*.
-Bibliographic fields like the *Status* shall be kept near to the top of the
-document after the document title.
-
-Example document fragment::
-
- TF-M Crypto Service design
- --------------------------
-
- :Author: Antonio de Angelis
- :Organization: Arm Limited
- :Contact: Antonio de Angelis <antonio.deangelis@arm.com>
- :Status: Draft
-
-Design documents are kept in three different sections of the documentation
-reflecting the status of the document. The status of the document determines
-the section it is in. Open (*Draft* and *Detailed* status) and accepted design
-documents shall be put to the ``docs/technical_references`` directory.
-
-.. important::
- - 'Author' and 'Organization' can be *OPTIONAL* but at least one of them is
- *MANDATORY*.
- - 'Contact' is *MANDATORY* and must be valid for contacting with 'Author'
- or 'Organization'.
- - 'Status' is *OPTIONAL* if the design document is managed under a version
- control tool. In this 'Status' field not available case, a guideline can be:
-
- - No review comments given design is a *Draft* design.
- - Positive review comments given design is a *Detailed* design.
- - Merged design is an *Accepted* design.
-
-Preparation
--------------
-In order to work on TF-M documentation the TF-M git repository has to be
-available locally. Setting up the documentation tools will allow pre-viewing the
-documentation file in preparation.
-For information on what tools are needed please refer to
-:doc:`TF-M getting started </docs/getting_started/tfm_getting_started>`. To see
-how to get a local copy of the TF-M repository please see
-:doc:`build instructions </docs/technical_references/instructions/tfm_build_instruction>`
-
-Process steps
--------------
-
-- Write the design proposal in the format that is described in this document
- with the *Status* set to *Draft* if *Status* field is provided. Put it to the
- ``docs/technical_references`` directory and create a pull request.
-- Start an e-mail thread on the
- `TF-M mailing list <mailto:tf-m@lists.trustedfirmware.org>`_ for discussing
- the proposal.
-- Build initial consensus within the community about the proposed design
- change, rework it according to the feedbacks and identify members who would
- like to participate in the detailed review.
-- When the "short list" of members who are willing to participate in the
- detailed review is established, set the *Status* field to *Detailed* if
- *Status* field is provided and push the change to Gerrit.
-- Add the members of the "short list" to the Gerrit review as reviewers.
-- The detailed discussion then takes place in the Gerrit review and gets
- recorded there.
- Additional changes are submitted as new commits to the review.
-- When the proposal is accepted and *Status* field is provided, the *Status*
- field is set to *Accepted* and update the change then get merged.
-
-.. uml::
-
- @startuml
- !define DRAFT_DIR **docs/technical_references/**
- !define REJECTED_DIR **docs/technical_references/rejected/**
- !define GERRIT_URL https://review.trustedfirmware.org
- !define GERRIT_LINK [[GERRIT_URL trustedfirmware.org]]
- !define MAINTAINER_RST_URL https://git.trustedfirmware.org/TF-M/trusted-firmware-m.git/tree/docs/maintainers.rst
- !define TFM_MAILING_LIST mailto:tf-m@lists.trustedfirmware.org
- !define NO_DECISION **no**
- !define YES_DECISION **yes**
- !define STATUS_DRAFT **Draft**
- !define STATUS_DETAILED **Detailed**
- !define STATUS_REJECTED **Rejected**
- !define STATUS_ACCEPTED **Accepted**
-
- title Design Proposal Process
-
- start
- :Create first draft.in [[http://docutils.sourceforge.net/rst.html ReST format]];
- :Set it's available 'Status' field to STATUS_DRAFT.;
-
- :Add your document under DRAFT_DIR.;
- :Create pull-request at GERRIT_LINK.;
- partition "Initial review." {
- :Start an e-mail thread at [[TFM_MAILING_LIST tf-m mailing list]].;
- repeat
- :Build initial consensus within the
- community about the proposed design change.;
- :Gather developers interested in detailed review.;
- repeat while (Ready for detailed review?)
- }
-
- partition "Detailed review." {
- :Set available 'Status' field to STATUS_DETAILED.;
- :Add reviewers to pull request.;
-
- repeat
- :Discuss design in Gerrit comments/notes.;
- :Log the result of discussions over
- other communication channels
- as Gerrit comments/notes.;
- :Push new document version if needed.;
- repeat while (Consensus reached?)
- }
-
- if (Design is accepted?) then (STATUS_ACCEPTED)
- :Sets available 'Status' field to STATUS_ACCEPTED.;
- ://Submit// the pull-request.;
- else (STATUS_REJECTED)
- endif
-
- stop
-
- @enduml
-
---------------
-
-*Copyright (c) 2019-2021, Arm Limited. All rights reserved.*