1#########################
2Design proposal guideline
3#########################
4
5The design proposal guideline specifies the steps to propose and upload design
6proposals to TF-M. Those steps are lightweight and flexible to make sure that
7contributors can focus more on actual code implementation and iteration.
8
9The guideline encourages developers to share design proposal via
10TF-M mailing list [1]_ and TF-M technical forum (tech forum) [2]_.
11The design details can be discussed via code reviews of actual implementations.
12
13Typical steps are shown as the diagram below.
14
15.. uml::
16
17  @startuml
18
19  title Design proposal process
20
21  [*] --> propose : Non-trivial changes
22
23  state "Propose general ideas" as propose {
24    state "TF-M mailing list" as mail_list : Contributors send emails to mailing list\nto describe the design.
25    state "TF-M tech forum" as tech_forum : Contributors present the design\nin tech forum.
26
27    [*] --> mail_list
28    [*] --> tech_forum
29  }
30
31  note bottom of propose : Optional but strongly recommended
32
33  [*] --> upload
34  note right of upload : No prerequisites
35  propose --> upload
36
37  state "Upstream changes" as upload : Contributors upstream code patch\nand integration guide to gerrit.
38  state "Code review" as review : Reviewer review changes of\ncode and documents.\nChanges pass verifications.
39  state "Broadcast patches" as broadcast : Contributors ask for review\nin mailing list.
40  state "Approve and merge" as approve : Code owners approve changes.\nMaintainers merge patches.
41
42  upload --> broadcast : Optional
43  upload --> review
44
45  broadcast --> review
46  review --> review : Update implementation
47  review --> approve
48  approve --> [*]
49
50  @enduml
51
52Discussion in TF-M mailing list and tech forum
53==============================================
54
55It is **highly recommended** to propose and discuss designs in TF-M mailing list
56or TF-M tech forum, before or while the code implementation is under review.
57
58It is efficient and flexible to directly discuss design proposal via TF-M
59mailing list and TF-M tech forum. Contributors can receive quick and broad
60feedback from TF-M community.
61
62Although it is optional to present the ideas in mailing list or tech forum, it
63will help reviewers understand the design much better and expedite the code
64review process.
65
66Code review of details
67======================
68
69It is straightforward and convenient for contributors and reviewers to
70deliberate over design and implementation details via code review.
71
72Contributors can implement their design proposal and upstream the patch set to
73TF-M gerrit [3]_ for code review.
74For non-trivial changes or new major features, it is **strongly suggested** to
75propose the design to TF-M mailing list and tech forum in advance.
76
77Contributors don't have to wait for any approvals before upstreaming patches,
78even if the changes are non-trivial.
79No formal design document in advance is required anymore.
80
81The review process is the same as the general one [4]_, with some specific
82requirements:
83
84  - Contributors can send an email to TF-M mailing list to ask for review.
85  - If it requires additional reviewers besides code owners and maintainers,
86    contributors shall add the specific reviewers in the review list.
87  - Authors shall clearly specify the design purpose and briefly describe the
88    implementation in the commit message.
89  - Authors shall put essential comments and notes in code for the code changes.
90
91Code owners and maintainers may require contributors to further verify the
92implementation besides normal per-patch CI test. Contributors shall provide the
93verification results as requested.
94
95Integration guide and manual
96============================
97
98Contributors can create an integration guide or a user manual to describe how to
99integrate the new features related to the design proposal.
100
101Contributors shall update the corresponding documents if the design changes
102existing implementation.
103
104*********
105Reference
106*********
107
108.. [1] `TF-M mailing list <https://lists.trustedfirmware.org/mailman3/lists/tf-m.lists.trustedfirmware.org/>`_
109
110.. [2] `TF-M technical forum <https://www.trustedfirmware.org/meetings/tf-m-technical-forum/>`_
111
112.. [3] `TF-M gerrit <https://review.trustedfirmware.org/q/project:TF-M/trusted-firmware-m>`_
113
114.. [4] :doc:`Contributing process </contributing/contributing_process>`
115
116-------------------
117
118*Copyright (c) 2022, Arm Limited. All rights reserved.*
119