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