Docs: Deprecate previous design proposal process
Replace previous design proposal process with the new design proposal
guideline. Remove the document.
Update contributing process document.
Change-Id: Ia31dbe2dad6c91bb6821c456e3929b9dd1b18d04
Signed-off-by: David Hu <david.hu@arm.com>
diff --git a/docs/contributing/contributing_process.rst b/docs/contributing/contributing_process.rst
index 8bd7e52..60faaec 100644
--- a/docs/contributing/contributing_process.rst
+++ b/docs/contributing/contributing_process.rst
@@ -19,7 +19,7 @@
<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>`
+ :doc:`Design Proposal Guideline </docs/contributing/tfm_design_proposal_guideline>`
for the TF-M project.
- After the design has been accepted by the maintainer(s), a corresponding
patch should be posted; follow guidelines below:
@@ -77,4 +77,4 @@
--------------
-*Copyright (c) 2017-2021, Arm Limited. All rights reserved.*
+*Copyright (c) 2017-2022, Arm Limited. All rights reserved.*
diff --git a/docs/contributing/tfm_design_proposal_guideline.rst b/docs/contributing/tfm_design_proposal_guideline.rst
index 0bd50e9..14f3804 100755
--- a/docs/contributing/tfm_design_proposal_guideline.rst
+++ b/docs/contributing/tfm_design_proposal_guideline.rst
@@ -2,54 +2,12 @@
Design proposal guideline
#########################
-**********
-Background
-**********
-
-The existing TF-M design proposal process [1]_ requires developers to upstream a
-formal design document in reStructuredText format to describe their design.
-That process further defines a 2-stage review process to review and approve the
-design document. That process ensures that critical designs are thoroughly
-reviewed by key reviewers, especially when TF-M was built up from scratch.
-
-Currently, since more and more developers are contributing to TF-M community
-with new requirements and features, the existing process sometimes becomes
-heavyweight for contributors and reviewers.
-
- - It is an additional effort for contributors to get familiar with
- reStructuredText syntax and complete the document with reStructuredText
- coding.
- - The whole review process may take a long time. It is required that design
- document shall be approved before code review starts. However, reviews of
- design document details and implementation details sometimes can be combined
- from the point of view of reviewers.
- - The approved design document might be frequently updated during later code
- review. The changes to design documents require review and approval again.
-
-Furthermore, it also brings some maintenance difficulties.
-
- - When implementation in code is changed, in theory, it is unnecessary to
- update the corresponding design document since it is a pure design proposal
- instead of a user guide.
- However, it is confusing if design document doesn't align with the
- implementation.
- - If the implementation is deprecated or the design document is out of date,
- there is no guideline yet to discuss whether or how the design document
- shall be deprecated as well or archived.
-
-TF-M design proposal process shall be simplified to speed up contribution,
-review and maintenance stages.
-
-*************
-New guideline
-*************
-
-The steps in the new design proposal guideline are lightweight and flexible to
-make sure that contributors can focus more on actual code implementation and
-iteration.
+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 [2]_ and TF-M technical forum (tech forum) [3]_.
+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.
@@ -112,7 +70,7 @@
deliberate over design and implementation details via code review.
Contributors can implement their design proposal and upstream the patch set to
-TF-M gerrit [4]_ for code review.
+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.
@@ -120,7 +78,7 @@
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 [5]_, with some specific
+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.
@@ -147,15 +105,13 @@
Reference
*********
-.. [1] :doc:`Design proposal process </docs/contributing/tfm_design_proposal_process>`
+.. [1] `TF-M mailing list <https://lists.trustedfirmware.org/mailman3/lists/tf-m.lists.trustedfirmware.org/>`_
-.. [2] `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 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] `TF-M gerrit <https://review.trustedfirmware.org/q/project:TF-M/trusted-firmware-m>`_
-
-.. [5] :doc:`Contributing process </docs/contributing/contributing_process>`
+.. [4] :doc:`Contributing process </docs/contributing/contributing_process>`
-------------------
diff --git a/docs/contributing/tfm_design_proposal_process.rst b/docs/contributing/tfm_design_proposal_process.rst
deleted file mode 100644
index 1f56140..0000000
--- a/docs/contributing/tfm_design_proposal_process.rst
+++ /dev/null
@@ -1,155 +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>
-
-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.*