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/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>`
-------------------