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 format with Sphinx extensions for documentation. Design documents shall be captured in this format.

Design documents are kept under version control at the project’s Gerrit server. 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 TF-M getting started. To see how to get a local copy of the TF-M repository please see build instructions

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 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.

---

Copyright (c) 2019-2021, Arm Limited. All rights reserved.