xref: /aosp_15_r20/external/pigweed/seed/0001.rst (revision 61c4878ac05f98d0ceed94b57d316916de578985)
1.. _seed-0001:
2
3======================
40001: The SEED Process
5======================
6.. seed::
7   :number: 1
8   :name: The SEED Process
9   :status: Accepted
10   :proposal_date: 2022-10-31
11   :cl: 116577
12   :authors: The Pigweed Team
13   :facilitator: Unassigned
14
15-------
16Summary
17-------
18SEEDs are the process through which substantial changes to Pigweed are proposed,
19reviewed, and decided by community stakeholders to collaboratively drive the
20project in a favorable direction.
21
22This document outlines the SEED process at a high level. Details about how SEEDs
23should be written and structured are described in :ref:`seed-0002`.
24
25----------
26Motivation
27----------
28As Pigweed and its community grow, it becomes important to ensure that the
29Pigweed team, Pigweed users, and other community stakeholders align on the
30future of the project. To date, development of Pigweed has primarily been
31driven by the core team, and community feedback has been mostly informal and
32undocumented.
33
34SEEDs are a formalized process for authoring, reviewing, and ratifying proposed
35changes to Pigweed.
36
37The SEED process has several goals.
38
39- Increase the visibility of proposed changes to Pigweed early on and allow
40  interested parties to engage in their design.
41
42- Maintain a public record of design decisions rendered during Pigweed's
43  development and the rationales behind them.
44
45- Ensure consistent API design across Pigweed modules through a formal team-wide
46  review process.
47
48Active SEEDs are discussed by the community through Gerrit code review comments
49as well as a SEEDs chatroom in Pigweed's Discord server. Decisions are
50ultimately rendered by a review committee of Pigweed team members.
51
52------------------------
53When is a SEED required?
54------------------------
55SEEDs should be written by any developer wishing to make a "substantial" change
56to Pigweed. Whether or not a change is considered "substantial" varies depending
57on what parts of Pigweed it touches and may change over time as the project
58evolves. Some general guidelines are established below.
59
60Examples of changes considered "substantial" include, but are not limited to:
61
62- Adding a new top-level module.
63
64- Modifying a widely-used public API.
65
66- A breaking update to typical Pigweed user workflows (bootstrap, build setup,
67  ``pw`` commands, etc.).
68
69- Changing any data interchange or storage protocol or format (e.g. transport
70  protocols, flash layout), unless the change is small and backwards compatible
71  (e.g. adding a field to an exchanged Protobuf message).
72
73- Changes to Pigweed's code policy, style guides, or other project-level
74  guidelines.
75
76- Whenever a Pigweed team member asks you to write a SEED.
77
78Conversely, the following changes would likely not require a SEED:
79
80- Fixing typos.
81
82- Refactoring internal module code without public API changes.
83
84- Adding minor parallel operations to existing APIs (e.g.
85  ``Read(ConstByteSpan)`` vs ``Read(const byte*, size_t)``).
86
87If you're unsure whether a change you wish to make requires a SEED, it's worth
88asking the Pigweed team in our Discord server prior to writing any code.
89
90-------
91Process
92-------
93Suppose you'd like to propose a new Pigweed RPC Over Smoke Signals protocol.
94
95#. If you haven't already, clone the Pigweed repository and set it up locally,
96   following the :ref:`docs-get-started-upstream` guide.
97
98#. Check out a clean Git branch off of ``main`` for your SEED.
99
100   .. code-block:: sh
101
102      git checkout -b seed-rpc-smoke-signals
103
104#. From an activated Pigweed environment, run the command ``pw seed create`` to
105   interactively create a SEED.
106
107   This command will prompt you for a SEED number (use the default it provides
108   unless you have a specific reason not to), title, and list of authors. Using
109   these, it will generate a SEED document and add it to the build, as well as
110   automatically creating two CLs in Gerrit: one claiming your SEED number, and
111   the second being the actual CL in which your SEED will be reviewed.
112
113   .. code-block:: none
114
115      Created two CLs for SEED-5309:
116
117      -  SEED-5309: Claim SEED number
118         <https://pigweed-review.googlesource.com/c/pigweed/pigweed/+/999998>
119
120      -  SEED-5309: Pigweed RPC Over Smoke Signals
121         <https://pigweed-review.googlesource.com/c/pigweed/pigweed/+/999999>
122
123   .. warning::
124
125      ``pw seed create`` will create and push Git commits for you. Make sure to
126      run it from a clean branch.
127
128#. Open the "Claim SEED number" CL and add GWSQ as a reviewer. Set
129   ``Pigweed-Auto-Submit`` to +1. This change will be approved promptly and
130   lock in your assigned SEED number.
131
132   .. image:: 0001/seed-index-gerrit.png
133
134#. Fill out your proposal document, using the :ref:`SEED template<seed-0002>` as
135   a guide.
136
137   If your SEED requires additional resources such as images, place them within
138   a subdirectory named identically to your document without the ``.rst``
139   extension. These should be listed as ``inputs`` in your SEED's GN doc group
140   target.
141
142   .. code-block::
143
144      seed/
145        ...
146        5309.rst
147        5309/
148          state-diagram.svg
149
150#. When you feel you have enough substantive content in your proposal to be
151   reviewed, push it up to Gerrit and switch the change from WIP to Active.
152   This will begin the open comments period.
153
154   Congrats! You are now a SEED author.
155
156#. The Pigweed team will now assign your SEED a SEED facilitator. The
157   facilitator will leave a comment on your SEED asking you to add their name
158   to the ``facilitator:`` entry in the header of your SEED.
159
160   The SEED facilitator is a member of the Pigweed team who will help move your
161   through the process. The SEED facilitator will be added as a reviewer on
162   your SEED and will be your primary point of contact on the Pigweed team.
163
164   Update the status of your SEED to ``"Open for Comments"`` and set the
165   assigned facilitator in its build target.
166
167   .. code-block::
168
169      pw_seed("5309") {
170        changelist = 987654
171        title = "pw_rpc Over Smoke Signals"
172        status = "Open for Comments"
173        author = "Your Name"
174        facilitator = "Your Facilitator"
175      }
176
177#. Create a thread for your SEED in the ``#seed`` channel of Pigweed's
178   `Discord server <https://discord.gg/M9NSeTA>`_.
179
180#. Engage with reviewers to iterate on your proposal through its comment period.
181
182#. During the comment period, the facilitator may comment that your proposal has
183   received "Approval of Intent" and request in the SEED comments for interested
184   reviewers to identify themselves.
185
186   The SEED status should be changed to ``Intent Approved``.
187
188   At this point, initial implementation of the feature may begin landing in
189   Pigweed upstream. Any CLs prior to the SEED landing should CC both the
190   facilitator and other commenters who've indictated their interest in
191   reviewing.
192
193   All code landed during this period should be marked as experimental and
194   protected by visibility limitations.
195
196#. When a tentative decision has been reached, the facilitator will comment on
197   your proposal with a summary of the discussion and reasoning, moving it into
198   its Last Call phase (as described in the
199   :ref:`Lifecycle <seed-0001-lifecycle>` section).
200
201#. Following the conclusion of the Last Call period (one week from the start of
202   Last Call), the facilitator will sign off on the CL with a +2 vote, allowing
203   it to be submitted. Once a +2 has been given, the SEED author should update
204   the SEED index and submit the CL.
205
206   Before submitting, update your SEED's GN target to point to the local RST
207   file and to reflect its final status.
208
209   .. code-block::
210
211      pw_seed("5309") {
212        sources = [ "5309.rst" ]
213        title = "pw_rpc Over Smoke Signals"
214        status = "Accepted"
215        author = "Your Name"
216      }
217
218---------------------------------------
219The relationship between SEEDs and code
220---------------------------------------
221Some common questions raised by participants in the SEED process revolve around
222how SEED proposals relate to implemented code. This section addresses several of
223those questions.
224
225When should implementation of a SEED proposal begin?
226====================================================
227.. admonition:: TL;DR
228
229   The SEED's author can start writing code as soon as the intent of the
230   proposal is approved.
231
232Generally speaking, there are two stages of approval for the majority of SEED
233proposals. The first is approval of the *intent* of the SEED --- that is,
234stakeholders agree that it represents a problem that Pigweed should address,
235and the general outline of the solution is reasonable.
236
237Following this comes the approval of the specific details of the proposed
238solution. Depending on the nature of the SEED, this could range
239from higher-level component hierarchies and interactions down to concrete API
240design and precise implementation details.
241
242Once the intent of a SEED is approved, authors are free to begin implementing
243code for their proposal if they wish. This can serve as an additional reference
244for reviewers to aid their understanding of the proposal, and allow both the
245proposal and implementation to co-evolve throughout the review process.
246
247Code written alongside an active SEED can be reviewed and even merged into
248Pigweed, hidden behind experimental feature flags.
249
250At what point is the code related to a SEED considered usable?
251==============================================================
252.. admonition:: TL;DR
253
254   Code written for a SEED is considered experimental and unstable until the
255   SEED is fully approved.
256
257It is possible for code to be written, reviewed, and committed to Pigweed while
258its SEED is still in the review process. As these changes end up in Pigweed's
259main, it naturally raises the question of whether or not it is usable by other
260modules, or even external projects.
261
262Any code which is approved and submitted while its SEED remains active will be
263treated as experimental and hidden behind a feature flag. These flags will be
264configurable by other modules and downstream projects, allowing dependencies on
265experimental code. All experimental features are unstable and subject to
266potentially large changes at any time, so depending on them in non-experimental
267contexts is strongly discouraged.
268
269There may be rare circumstances where particularly time-sensitive code is
270required by projects with whom Pigweed works in close collaboration before a
271full SEED approval cycle can be completed. In these instances, the project may
272begin to depend on experimental code prematurely, and Pigweed will assist them
273with keeping up-to-date as it evolves. This type of usage is limited to only
274exceptional circumstances. In almost all cases, experimental code should be used
275at a project's own risk.
276
277Will approved SEEDs be updated in response to code changes?
278===========================================================
279.. admonition:: TL;DR
280
281   Approved SEEDs will not be updated as code evolves. Use module documentation
282   as a current reference.
283
284SEED documents are intended to capture decisions made at a point in time with
285their justification. They are not living documents which reflect the current
286state of the codebase. Generally speaking, SEEDs will not be updated following
287their acceptance and will likely diverge from the actual code as time passes.
288Some SEEDs may even become entirely obsolete if the team revisited the issue and
289decided to move in a different direction, becoming purely a historical record of
290design decisions.
291
292There are exceptions when a SEED may be modified after it has been approved;
293typically, these will occur shortly after the approval if its implementer finds
294that an important detail was incorrect or missing.
295
296If a SEED/s content is obsolete or outdated, it should ideally be marked as
297such by adding a notice or warning to the top of the SEED. However, these
298indications are marked on a best-effort basis, so SEEDs should not be be used as
299the primary source of documentation for a Pigweed feature.
300
301Users should instead rely on module documentation for up-to-date
302information about the state of a Pigweed module or feature. SEEDs can be used as
303an additional resource to learn *why* something was designed the way that it is,
304but is never necessary to understand functionality or usage.
305
306--------------
307SEED documents
308--------------
309SEEDs are written as ReST documents integrated with the rest of Pigweed's
310documentation. They live directly within the core Pigweed repository, under a
311top-level ``seed/`` subdirectory.
312
313The structure of SEED documents themselves, their format, required sections, and
314other considerations are outlined in :ref:`seed-0002`.
315
316The first 100 SEEDs (0000-0100) are *Meta-SEEDs*. These are reserved for
317internal Pigweed usage and generally detail SEED-related processes. Unlike
318regular SEEDs, Meta-SEEDs are living documents which may be revised over time.
319
320.. _seed-0001-lifecycle:
321
322-----------------------
323The lifecycle of a SEED
324-----------------------
325A SEED proposal undergoes several phases between first being published and a
326final decision.
327
328:bdg-primary-line:`Draft` **The SEED is a work-in-progress and not yet ready
329for comments.**
330
331- The SEED exists in Gerrit as a Work-In-Progress (WIP) change.
332- Has an assigned SEED number and exists in the index.
333- Not yet ready to receive feedback.
334
335:bdg-primary-line:`Intent Approved` **The idea behind the SEED has been approved
336for further investigation.**
337
338- The SEED exists in Gerrit as a Work-In-Progress (WIP) change.
339- Has an assigned SEED number and exists in the index.
340- The main proposal is not yet fully written out, but may start receiving
341  preliminary rounds of feedback.
342
343:bdg-primary:`Open for Comments` **The SEED is soliciting feedback.**
344
345- The SEED has sufficient substance to be reviewed, as determined by its
346  author.
347- A thread for the SEED is created in Discord to promote the proposal and open
348  discussion.
349- Interested parties comment on the SEED to evaluate the proposal, raise
350  questions and concerns, and express support or opposition.
351- Back and forth discussion between the author and reviewers, resulting in
352  modifications to the document.
353- The SEED remains open for as long as necessary. Internally, Pigweed's review
354  committee will regularly meet to consider active SEEDs and determine when to
355  advance to them the next stage.
356- Open SEEDs are assigned facilitators in the core Pigweed team, who are
357  primarily responsible for engaging with the author to move the SEED through
358  its review process.
359
360:bdg-warning:`Last Call` **A tentative decision has been reached, but
361commenters may raise final objections.**
362
363- A tentative decision on the SEED has been made. The decision is issued at the
364  best judgement of the SEED's facilitator when they feel there has been
365  sufficient discussion on the tradeoffs of the proposal to do so.
366- Transition is triggered manually by its facilitator, with a comment on the
367  likely outcome of the SEED (acceptance / rejection).
368- On entering Last Call, the visibility of the SEED is widely boosted through
369  Pigweed's communication channels (Discord, mailing list, Pigweed Live, etc.)
370  to solicit any strong objections from stakeholders.
371- Typically, Last Call lasts for a set period of 7 calendar days, after which
372  the final decision is formalized.
373- If any substantial new arguments are raised during Last Call, the review
374  committee may decide to re-open the discussion, returning the SEED to a
375  commenting phase.
376
377:bdg-success:`Accepted` **The proposal is ratified and ready for
378implementation.**
379
380- The SEED is submitted into the Pigweed repository.
381- A tracking bug is created for the implementation, if applicable.
382- The SEED may no longer be modified (except minor changes such as typos).
383  Follow-up discussions on the same topic require a new SEED.
384
385:bdg-danger:`Rejected` **The proposal has been turned down.**
386
387- The SEED is submitted into the Pigweed repository to provide a permanent
388  record of the considerations made for future reference.
389- The SEED may no longer be modified.
390
391:bdg-secondary:`Deprecated` **The proposal was originally accepted and
392implemented but later removed.**
393
394- The proposal was once implemented but later undone.
395- The SEED's changelog contains justification for the deprecation.
396
397:bdg-info:`Superseded` **The proposal was originally accepted and implemented
398but significant portions were later overruled by a different SEED.**
399
400- A newer SEED proposal revisits the same topic and proposal and redesigns
401  significant parts of the original.
402- The SEED is marked as superseded with a reference to the newer proposal.
403
404:bdg-secondary-line:`On Hold` **The SEED is temporarily on pause due to other
405priorities, without a decision being made on its acceptance.**
406
407- The SEED has an assigned number, and a Gerrit CL with previous rounds of
408  feedback. The CL is switched to WIP.
409- The SEED is closed to additional feedback during the hold period.
410
411---------
412Rationale
413---------
414
415Document format
416===============
417Three different documentation formats are considered for SEEDs:
418
419- **ReST:** Used for Pigweed's existing documentation, making it a natural
420  option.
421- **Google Docs:** The traditional way of writing SEED-like investigation and
422  design documents.
423- **Markdown:** Ubiquitous across open-source projects, with extensive tooling
424  available.
425
426Summary
427-------
428Based on the evaluated criteria, ReST documents provide the best overall SEED
429experience. The primary issues with ReST exist around contributor tooling, which
430may be mitigated with additional investment from the Pigweed team.
431
432The table below details the main criteria evaluated for each format, with more
433detailed explanations following.
434
435.. list-table::
436   :widths: 55 15 15 15
437   :header-rows: 1
438
439   * - Criterion
440     - ReST
441     - Markdown
442     - Google Docs
443   * - Straightforward integration with existing docs
444     - ✅
445     - ❌
446     - ❌
447   * - Indexable on `pigweed.dev <https://pigweed.dev>`_
448     - ✅
449     - ✅
450     - ❌
451   * - Auditable through source control
452     - ✅
453     - ✅
454     - ❌
455   * - Archive of review comments and changes
456     - ✅
457     - ✅
458     - ❌
459   * - Accessible to contributors
460     - ❌
461     - ✅
462     - ✅
463   * - Extensive styling and formatting options
464     - ✅
465     - ❌
466     - ✅
467   * - Easy sharing between Google and external contributors
468     - ✅
469     - ✅
470     - ❌
471
472Integration
473-----------
474.. admonition:: Goal
475
476   SEED documents should seamlessly integrate with the rest of Pigweed's docs.
477
478As all of Pigweed's documentation is written using ReST, it becomes a natural
479choice for SEEDs. The use of other formats requires additional scaffolding and
480may not provide as seamless of an experience.
481
482Indexability
483------------
484.. admonition:: Goal
485
486   Design decisions in SEEDs should be readily available for Pigweed users.
487
488`pigweed.dev <https://pigweed.dev>`_ has a search function allowing users to
489search the site for Pigweed-related keywords. As SEEDs contain design discussion
490and rationales, having them appear in these searches offers useful information
491to users.
492
493The search function is provided by Pigweed's Sphinx build, so only documents
494which exist as part of that (ReST / Markdown) are indexed.
495
496Auditability
497------------
498.. admonition:: Goal
499
500   Changes to SEED documents should be reviewed and recorded.
501
502ReST and Markdown documents exist directly within Pigweed's source repository
503after being submitted, requiring any further changes to go through a code
504review process.
505
506Conversely, Google Docs may be edited by anyone with access, making them prone
507to unintentional modification.
508
509Archive of discussions
510----------------------
511.. admonition:: Goal
512
513   Discussions during the review of a SEED should be well-archived for
514   future reference.
515
516ReST and Markdown documentation are submitted through Gerrit and follow the
517standard code review process. Review comments on the changes are saved in
518Gerrit and are easily revisited. Incremental updates to the SEED during the
519review process are saved as patch sets.
520
521Comments in Google Docs are more difficult to find once they are resolved, and
522document changes do not exist as clearly-defined snapshots, making the history
523of a SEED harder to follow.
524
525Accessibility
526-------------
527.. admonition:: Goal
528
529   SEEDs should be easy for contributors to write.
530
531Both Markdown and Google Docs are easy to write, familiar to many, and have
532extensive tooling available. SEED documents can be written outside of the
533Pigweed ecosystem using authors' preferred tools.
534
535ReST, on the other hand, is an unfamiliar and occasionally strange format, and
536its usage for SEEDs is heavily tied to Pigweed's documentation build. Authors
537are required to set up and constantly re-run this build, slowing iteration.
538
539Format and styling
540------------------
541.. admonition:: Goal
542
543   SEED authors should have options for formatting various kinds of information
544   and data in their proposals.
545
546Markdown intentionally only offers limited control over document formatting,
547whereas ReST has a wide selection of directives and Google Docs functions as a
548traditional WYSIWYG editor, making them far more flexible.
549
550Sharing between Google and non-Google
551-------------------------------------
552.. admonition:: Goal
553
554   Both Google and non-Google contributors should easily be able to write and
555   review SEEDs.
556
557Due to security and legal concerns, managing ownership of Google Docs between
558internal and external contributors is nontrivial.
559
560Text documentation formats like Markdown and ReST live within the Pigweed
561repository, and as such follow the standard code contribution process.
562