Design proposal guideline
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 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.
![@startuml
title Design proposal process
[*] --> propose : Non-trivial changes
state "Propose general ideas" as propose {
state "TF-M mailing list" as mail_list : Contributors send emails to mailing list\nto describe the design.
state "TF-M tech forum" as tech_forum : Contributors present the design\nin tech forum.
[*] --> mail_list
[*] --> tech_forum
}
note bottom of propose : Optional but strongly recommended
[*] --> upload
note right of upload : No prerequisites
propose --> upload
state "Upstream changes" as upload : Contributors upstream code patch\nand integration guide to gerrit.
state "Code review" as review : Reviewer review changes of\ncode and documents.\nChanges pass verifications.
state "Broadcast patches" as broadcast : Contributors ask for review\nin mailing list.
state "Approve and merge" as approve : Code owners approve changes.\nMaintainers merge patches.
upload --> broadcast : Optional
upload --> review
broadcast --> review
review --> review : Update implementation
review --> approve
approve --> [*]
@enduml](../_images/plantuml-168e57fe4f59ac4073b4596e299cecdb64d77f67.png)
Discussion in TF-M mailing list and tech forum
It is highly recommended to propose and discuss designs in TF-M mailing list or TF-M tech forum, before or while the code implementation is under review.
It is efficient and flexible to directly discuss design proposal via TF-M mailing list and TF-M tech forum. Contributors can receive quick and broad feedback from TF-M community.
Although it is optional to present the ideas in mailing list or tech forum, it will help reviewers understand the design much better and expedite the code review process.
Code review of details
It is straightforward and convenient for contributors and reviewers to deliberate over design and implementation details via code review.
Contributors can implement their design proposal and upstream the patch set to 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.
Contributors don’t have to wait for any approvals before upstreaming patches, 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 4, with some specific requirements:
Contributors can send an email to TF-M mailing list to ask for review.
If it requires additional reviewers besides code owners and maintainers, contributors shall add the specific reviewers in the review list.
Authors shall clearly specify the design purpose and briefly describe the implementation in the commit message.
Authors shall put essential comments and notes in code for the code changes.
Code owners and maintainers may require contributors to further verify the implementation besides normal per-patch CI test. Contributors shall provide the verification results as requested.
Integration guide and manual
Contributors can create an integration guide or a user manual to describe how to integrate the new features related to the design proposal.
Contributors shall update the corresponding documents if the design changes existing implementation.
Reference
Copyright (c) 2022, Arm Limited. All rights reserved.