Design proposal process


Gyorgy Szing


Arm Limited


Gyorgy Szing <>

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.


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

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.


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


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.

!define DRAFT_DIR **docs/technical_references/**
!define REJECTED_DIR **docs/technical_references/rejected/**
!define GERRIT_URL
!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

:Create first [[ 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]].;
        :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.;

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



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