Doc: add design proposal process documentation.
Add new document section for processes and new document describing the
design proposal process.
Added CMake support for status handling of design documents.
Improved update process (dependency handling) of Sphinx documentation.
Fixed issue where the intermediate document files from the build
directory were added to Sphinx output if the build directory was placed
under TF-M root directory.
Change-Id: Ie21abe120ffcb5f0a79ddf1c398eb198959878f3
Signed-off-by: Gyorgy Szing <Gyorgy.Szing@arm.com>
diff --git a/docs/index.rst b/docs/index.rst.in
similarity index 82%
rename from docs/index.rst
rename to docs/index.rst.in
index f9c1282..e2151a4 100644
--- a/docs/index.rst
+++ b/docs/index.rst.in
@@ -3,8 +3,11 @@
..
The build-system will copy all documents into a temporary directory tree
before the documentation is built.
- This fill will be copied to the top level and thus please use relative paths
+ This file will be copied to the top level and thus please use relative paths
as if this file would be in <TFM_ROOT_DIR>.
+
+ The values between @ characters will be filled in by CMake.
+
Welcome to TF-M's documentation!
================================
@@ -29,6 +32,14 @@
.. toctree::
:maxdepth: 2
+ :caption: Processes
+ :glob:
+ :hidden:
+
+ docs/processes/**
+
+.. toctree::
+ :maxdepth: 2
:caption: Secure services
:glob:
:hidden:
@@ -57,7 +68,7 @@
:glob:
:hidden:
- docs/design_documents/*
+ @ACCEPTED_DD_LIST@
.. toctree::
:caption: Draft design documents
@@ -65,7 +76,7 @@
:glob:
:hidden:
- docs/design_documents/drafts/*
+ @DRAFT_DD_LIST@
.. toctree::
:caption: Rejected design documents
@@ -73,7 +84,7 @@
:glob:
:hidden:
- docs/design_documents/rejected/*
+ @REJECTED_DD_LIST@
.. include:: readme.rst
diff --git a/docs/processes/tfm_design_proposal_process.rst b/docs/processes/tfm_design_proposal_process.rst
new file mode 100644
index 0000000..478220e
--- /dev/null
+++ b/docs/processes/tfm_design_proposal_process.rst
@@ -0,0 +1,151 @@
+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 changing Trusted Firmware design. It
+specifies:
+
+ - the documentation format to be used
+ - the information which shall be captured
+ - the steps of the process
+ - and 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/design_documents``
+directory and rejected documents to the ``docs/design_documents/rejected``
+directory.
+
+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:`sw requirements </docs/user_guides/tfm_sw_requirement>`. To see how to get
+a local copy of the TF-M repository please see
+:doc:`build instructions </docs/user_guides/tfm_build_instruction>`
+
+Process steps
+-------------
+
+- Write the design proposal in the format that is described in this document
+ with the status set to *Draft*. Put it to the ``docs/design_documents``
+ 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* 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, the status field is set to *Accepted*, the
+ change updated and merged.
+- If at any point the proposal is rejected its status field is set to
+ *Rejected*, and the document is moved to the *rejected design documents*
+ section.
+
+.. uml::
+
+ @startuml
+ !define DRAFT_DIR **docs/design_documents/**
+ !define REJECTED_DIR **docs/design_documents/rejected/**
+ !define GERRIT_URL https://review.trustedfirmware.org
+ !define GERRIT_LINK [[GERRIT_URL trustedfirmware.org]]
+ !define MAINTAINER_RST_URL https://git.trustedfirmware.org/trusted-firmware-m.git/tree/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 status 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 document status 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 rejected?) then (YES_DECISION)
+ :Set document status to STATUS_REJECTED.;
+ :Move the document to REJECTED_DIR.;
+ else (NO_DECISION)
+ :Sets the document status to STATUS_ACCEPTED.;
+ endif
+
+ ://Submit// the pull-request.;
+ stop
+
+ @enduml
+
+--------------
+
+*Copyright (c) 2019, Arm Limited. All rights reserved.*