diff options
Diffstat (limited to 'docs/contributing')
-rw-r--r-- | docs/contributing/code_review_guide.rst | 32 | ||||
-rw-r--r-- | docs/contributing/coding_guide.rst | 8 | ||||
-rw-r--r-- | docs/contributing/contributing_process.rst | 117 | ||||
-rw-r--r-- | docs/contributing/dco.rst | 2 | ||||
-rw-r--r-- | docs/contributing/doc_guidelines.rst | 74 | ||||
-rw-r--r-- | docs/contributing/index.rst | 10 | ||||
-rw-r--r-- | docs/contributing/lic.rst | 2 | ||||
-rw-r--r-- | docs/contributing/maintainers.rst | 161 | ||||
-rwxr-xr-x | docs/contributing/tfm_design_proposal_guideline.rst | 118 | ||||
-rw-r--r-- | docs/contributing/tfm_design_proposal_process.rst | 156 |
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.* |