| .. _seed-0001: |
| |
| ====================== |
| 0001: The SEED Process |
| ====================== |
| .. seed:: |
| :number: 1 |
| :name: The SEED Process |
| :status: Accepted |
| :proposal_date: 2022-10-31 |
| :cl: 116577 |
| :authors: The Pigweed Team |
| :facilitator: Unassigned |
| |
| ------- |
| Summary |
| ------- |
| SEEDs are the process through which substantial changes to Pigweed are proposed, |
| reviewed, and decided by community stakeholders to collaboratively drive the |
| project in a favorable direction. |
| |
| This document outlines the SEED process at a high level. Details about how SEEDs |
| should be written and structured are described in :ref:`seed-0002`. |
| |
| ---------- |
| Motivation |
| ---------- |
| As Pigweed and its community grow, it becomes important to ensure that the |
| Pigweed team, Pigweed users, and other community stakeholders align on the |
| future of the project. To date, development of Pigweed has primarily been |
| driven by the core team, and community feedback has been mostly informal and |
| undocumented. |
| |
| SEEDs are a formalized process for authoring, reviewing, and ratifying proposed |
| changes to Pigweed. |
| |
| The SEED process has several goals. |
| |
| - Increase the visibility of proposed changes to Pigweed early on and allow |
| interested parties to engage in their design. |
| |
| - Maintain a public record of design decisions rendered during Pigweed's |
| development and the rationales behind them. |
| |
| - Ensure consistent API design across Pigweed modules through a formal team-wide |
| review process. |
| |
| Active SEEDs are discussed by the community through Gerrit code review comments |
| as well as a SEEDs chatroom in Pigweed's Discord server. Decisions are |
| ultimately rendered by a review committee of Pigweed team members. |
| |
| ------------------------ |
| When is a SEED required? |
| ------------------------ |
| SEEDs should be written by any developer wishing to make a "substantial" change |
| to Pigweed. Whether or not a change is considered "substantial" varies depending |
| on what parts of Pigweed it touches and may change over time as the project |
| evolves. Some general guidelines are established below. |
| |
| Examples of changes considered "substantial" include, but are not limited to: |
| |
| - Adding a new top-level module. |
| |
| - Modifying a widely-used public API. |
| |
| - A breaking update to typical Pigweed user workflows (bootstrap, build setup, |
| ``pw`` commands, etc.). |
| |
| - Changing any data interchange or storage protocol or format (e.g. transport |
| protocols, flash layout), unless the change is small and backwards compatible |
| (e.g. adding a field to an exchanged Protobuf message). |
| |
| - Changes to Pigweed's code policy, style guides, or other project-level |
| guidelines. |
| |
| - Whenever a Pigweed team member asks you to write a SEED. |
| |
| Conversely, the following changes would likely not require a SEED: |
| |
| - Fixing typos. |
| |
| - Refactoring internal module code without public API changes. |
| |
| - Adding minor parallel operations to existing APIs (e.g. |
| ``Read(ConstByteSpan)`` vs ``Read(const byte*, size_t)``). |
| |
| If you're unsure whether a change you wish to make requires a SEED, it's worth |
| asking the Pigweed team in our Discord server prior to writing any code. |
| |
| ------- |
| Process |
| ------- |
| Suppose you'd like to propose a new Pigweed RPC Over Smoke Signals protocol. |
| |
| #. If you haven't already, clone the Pigweed repository and set it up locally, |
| following the :ref:`docs-get-started-upstream` guide. |
| |
| #. Check out a clean Git branch off of ``main`` for your SEED. |
| |
| .. code-block:: sh |
| |
| git checkout -b seed-rpc-smoke-signals |
| |
| #. From an activated Pigweed environment, run the command ``pw seed create`` to |
| interactively create a SEED. |
| |
| This command will prompt you for a SEED number (use the default it provides |
| unless you have a specific reason not to), title, and list of authors. Using |
| these, it will generate a SEED document and add it to the build, as well as |
| automatically creating two CLs in Gerrit: one claiming your SEED number, and |
| the second being the actual CL in which your SEED will be reviewed. |
| |
| .. code-block:: none |
| |
| Created two CLs for SEED-5309: |
| |
| - SEED-5309: Claim SEED number |
| <https://pigweed-review.googlesource.com/c/pigweed/pigweed/+/999998> |
| |
| - SEED-5309: Pigweed RPC Over Smoke Signals |
| <https://pigweed-review.googlesource.com/c/pigweed/pigweed/+/999999> |
| |
| .. warning:: |
| |
| ``pw seed create`` will create and push Git commits for you. Make sure to |
| run it from a clean branch. |
| |
| #. Open the "Claim SEED number" CL and add GWSQ as a reviewer. Set |
| ``Pigweed-Auto-Submit`` to +1. This change will be approved promptly and |
| lock in your assigned SEED number. |
| |
| .. image:: 0001-the-seed-process/seed-index-gerrit.png |
| |
| #. Fill out your proposal document, using the :ref:`SEED template<seed-0002>` as |
| a guide. |
| |
| If your SEED requires additional resources such as images, place them within |
| a subdirectory named identically to your document without the ``.rst`` |
| extension. These should be listed as ``inputs`` in your SEED's GN doc group |
| target. |
| |
| .. code-block:: |
| |
| seed/ |
| ... |
| 5309-pw_rpc-over-smoke-signals.rst |
| 5309-pw_rpc-over-smoke-signals/ |
| state-diagram.svg |
| |
| #. When you feel you have enough substantive content in your proposal to be |
| reviewed, push it up to Gerrit and switch the change from WIP to Active. |
| This will begin the open comments period. |
| |
| Congrats! You are now a SEED author. |
| |
| #. The Pigweed team will now assign your SEED a SEED facilitator. The |
| facilitator will leave a comment on your SEED asking you to add their name |
| to the ``facilitator:`` entry in the header of your SEED. |
| |
| The SEED facilitator is a member of the Pigweed team who will help move your |
| through the process. The SEED facilitator will be added as a reviewer on |
| your SEED and will be your primary point of contact on the Pigweed team. |
| |
| Update the status of your SEED to ``"Open for Comments"`` and set the |
| assigned facilitator in its build target. |
| |
| .. code-block:: |
| |
| pw_seed("5309") { |
| changelist = 987654 |
| title = "pw_rpc Over Smoke Signals" |
| status = "Open for Comments" |
| author = "Your Name" |
| facilitator = "Your Facilitator" |
| } |
| |
| #. Create a thread for your SEED in the ``#seed`` channel of Pigweed's |
| `Discord server <https://discord.gg/M9NSeTA>`_. |
| |
| #. Engage with reviewers to iterate on your proposal through its comment period. |
| |
| #. During the comment period, the facilitator may comment that your proposal has |
| received "Approval of Intent" and request in the SEED comments for interested |
| reviewers to identify themselves. |
| |
| The SEED status should be changed to ``Intent Approved``. |
| |
| At this point, initial implementation of the feature may begin landing in |
| Pigweed upstream. Any CLs prior to the SEED landing should CC both the |
| facilitator and other commenters who've indictated their interest in |
| reviewing. |
| |
| All code landed during this period should be marked as experimental and |
| protected by visibility limitations. |
| |
| #. When a tentative decision has been reached, the facilitator will comment on |
| your proposal with a summary of the discussion and reasoning, moving it into |
| its Last Call phase (as described in the |
| :ref:`Lifecycle <seed-0001-lifecycle>` section). |
| |
| #. Following the conclusion of the Last Call period (one week from the start of |
| Last Call), the facilitator will sign off on the CL with a +2 vote, allowing |
| it to be submitted. Once a +2 has been given, the SEED author should update |
| the SEED index and submit the CL. |
| |
| Before submitting, update your SEED's GN target to point to the local RST |
| file and to reflect its final status. |
| |
| .. code-block:: |
| |
| pw_seed("5309") { |
| sources = [ "5309-pw_rpc-over-smoke-signals.rst" ] |
| title = "pw_rpc Over Smoke Signals" |
| status = "Accepted" |
| author = "Your Name" |
| } |
| |
| --------------------------------------- |
| The relationship between SEEDs and code |
| --------------------------------------- |
| Some common questions raised by participants in the SEED process revolve around |
| how SEED proposals relate to implemented code. This section addresses several of |
| those questions. |
| |
| When should implementation of a SEED proposal begin? |
| ==================================================== |
| .. admonition:: TL;DR |
| |
| The SEED's author can start writing code as soon as the intent of the |
| proposal is approved. |
| |
| Generally speaking, there are two stages of approval for the majority of SEED |
| proposals. The first is approval of the *intent* of the SEED --- that is, |
| stakeholders agree that it represents a problem that Pigweed should address, |
| and the general outline of the solution is reasonable. |
| |
| Following this comes the approval of the specific details of the proposed |
| solution. Depending on the nature of the SEED, this could range |
| from higher-level component hierarchies and interactions down to concrete API |
| design and precise implementation details. |
| |
| Once the intent of a SEED is approved, authors are free to begin implementing |
| code for their proposal if they wish. This can serve as an additional reference |
| for reviewers to aid their understanding of the proposal, and allow both the |
| proposal and implementation to co-evolve throughout the review process. |
| |
| Code written alongside an active SEED can be reviewed and even merged into |
| Pigweed, hidden behind experimental feature flags. |
| |
| At what point is the code related to a SEED considered usable? |
| ============================================================== |
| .. admonition:: TL;DR |
| |
| Code written for a SEED is considered experimental and unstable until the |
| SEED is fully approved. |
| |
| It is possible for code to be written, reviewed, and committed to Pigweed while |
| its SEED is still in the review process. As these changes end up in Pigweed's |
| main, it naturally raises the question of whether or not it is usable by other |
| modules, or even external projects. |
| |
| Any code which is approved and submitted while its SEED remains active will be |
| treated as experimental and hidden behind a feature flag. These flags will be |
| configurable by other modules and downstream projects, allowing dependencies on |
| experimental code. All experimental features are unstable and subject to |
| potentially large changes at any time, so depending on them in non-experimental |
| contexts is strongly discouraged. |
| |
| There may be rare circumstances where particularly time-sensitive code is |
| required by projects with whom Pigweed works in close collaboration before a |
| full SEED approval cycle can be completed. In these instances, the project may |
| begin to depend on experimental code prematurely, and Pigweed will assist them |
| with keeping up-to-date as it evolves. This type of usage is limited to only |
| exceptional circumstances. In almost all cases, experimental code should be used |
| at a project's own risk. |
| |
| Will approved SEEDs be updated in response to code changes? |
| =========================================================== |
| .. admonition:: TL;DR |
| |
| Approved SEEDs will not be updated as code evolves. Use module documentation |
| as a current reference. |
| |
| SEED documents are intended to capture decisions made at a point in time with |
| their justification. They are not living documents which reflect the current |
| state of the codebase. Generally speaking, SEEDs will not be updated following |
| their acceptance and will likely diverge from the actual code as time passes. |
| Some SEEDs may even become entirely obsolete if the team revisited the issue and |
| decided to move in a different direction, becoming purely a historical record of |
| design decisions. |
| |
| There are exceptions when a SEED may be modified after it has been approved; |
| typically, these will occur shortly after the approval if its implementer finds |
| that an important detail was incorrect or missing. |
| |
| If a SEED/s content is obsolete or outdated, it should ideally be marked as |
| such by adding a notice or warning to the top of the SEED. However, these |
| indications are marked on a best-effort basis, so SEEDs should not be be used as |
| the primary source of documentation for a Pigweed feature. |
| |
| Users should instead rely on module documentation for up-to-date |
| information about the state of a Pigweed module or feature. SEEDs can be used as |
| an additional resource to learn *why* something was designed the way that it is, |
| but is never necessary to understand functionality or usage. |
| |
| -------------- |
| SEED documents |
| -------------- |
| SEEDs are written as ReST documents integrated with the rest of Pigweed's |
| documentation. They live directly within the core Pigweed repository, under a |
| top-level ``seed/`` subdirectory. |
| |
| The structure of SEED documents themselves, their format, required sections, and |
| other considerations are outlined in :ref:`seed-0002`. |
| |
| The first 100 SEEDs (0000-0100) are *Meta-SEEDs*. These are reserved for |
| internal Pigweed usage and generally detail SEED-related processes. Unlike |
| regular SEEDs, Meta-SEEDs are living documents which may be revised over time. |
| |
| .. _seed-0001-lifecycle: |
| |
| ----------------------- |
| The lifecycle of a SEED |
| ----------------------- |
| A SEED proposal undergoes several phases between first being published and a |
| final decision. |
| |
| :bdg-primary-line:`Draft` **The SEED is a work-in-progress and not yet ready |
| for comments.** |
| |
| - The SEED exists in Gerrit as a Work-In-Progress (WIP) change. |
| - Has an assigned SEED number and exists in the index. |
| - Not yet ready to receive feedback. |
| |
| :bdg-primary:`Open for Comments` **The SEED is soliciting feedback.** |
| |
| - The SEED has sufficient substance to be reviewed, as determined by its |
| author. |
| - A thread for the SEED is created in Discord to promote the proposal and open |
| discussion. |
| - Interested parties comment on the SEED to evaluate the proposal, raise |
| questions and concerns, and express support or opposition. |
| - Back and forth discussion between the author and reviewers, resulting in |
| modifications to the document. |
| - The SEED remains open for as long as necessary. Internally, Pigweed's review |
| committee will regularly meet to consider active SEEDs and determine when to |
| advance to them the next stage. |
| - Open SEEDs are assigned facilitators in the core Pigweed team, who are |
| primarily responsible for engaging with the author to move the SEED through |
| its review process. |
| |
| :bdg-warning:`Last Call` **A tentative decision has been reached, but |
| commenters may raise final objections.** |
| |
| - A tentative decision on the SEED has been made. The decision is issued at the |
| best judgement of the SEED's facilitator when they feel there has been |
| sufficient discussion on the tradeoffs of the proposal to do so. |
| - Transition is triggered manually by its facilitator, with a comment on the |
| likely outcome of the SEED (acceptance / rejection). |
| - On entering Last Call, the visibility of the SEED is widely boosted through |
| Pigweed's communication channels (Discord, mailing list, Pigweed Live, etc.) |
| to solicit any strong objections from stakeholders. |
| - Typically, Last Call lasts for a set period of 7 calendar days, after which |
| the final decision is formalized. |
| - If any substantial new arguments are raised during Last Call, the review |
| committee may decide to re-open the discussion, returning the SEED to a |
| commenting phase. |
| |
| :bdg-success:`Accepted` **The proposal is ratified and ready for |
| implementation.** |
| |
| - The SEED is submitted into the Pigweed repository. |
| - A tracking bug is created for the implementation, if applicable. |
| - The SEED may no longer be modified (except minor changes such as typos). |
| Follow-up discussions on the same topic require a new SEED. |
| |
| :bdg-danger:`Rejected` **The proposal has been turned down.** |
| |
| - The SEED is submitted into the Pigweed repository to provide a permanent |
| record of the considerations made for future reference. |
| - The SEED may no longer be modified. |
| |
| :bdg-secondary:`Deprecated` **The proposal was originally accepted and |
| implemented but later removed.** |
| |
| - The proposal was once implemented but later undone. |
| - The SEED's changelog contains justification for the deprecation. |
| |
| :bdg-info:`Superseded` **The proposal was originally accepted and implemented |
| but significant portions were later overruled by a different SEED.** |
| |
| - A newer SEED proposal revisits the same topic and proposal and redesigns |
| significant parts of the original. |
| - The SEED is marked as superseded with a reference to the newer proposal. |
| |
| --------- |
| Rationale |
| --------- |
| |
| Document format |
| =============== |
| Three different documentation formats are considered for SEEDs: |
| |
| - **ReST:** Used for Pigweed's existing documentation, making it a natural |
| option. |
| - **Google Docs:** The traditional way of writing SEED-like investigation and |
| design documents. |
| - **Markdown:** Ubiquitous across open-source projects, with extensive tooling |
| available. |
| |
| Summary |
| ------- |
| Based on the evaluated criteria, ReST documents provide the best overall SEED |
| experience. The primary issues with ReST exist around contributor tooling, which |
| may be mitigated with additional investment from the Pigweed team. |
| |
| The table below details the main criteria evaluated for each format, with more |
| detailed explanations following. |
| |
| .. list-table:: |
| :widths: 55 15 15 15 |
| :header-rows: 1 |
| |
| * - Criterion |
| - ReST |
| - Markdown |
| - Google Docs |
| * - Straightforward integration with existing docs |
| - ✅ |
| - ❌ |
| - ❌ |
| * - Indexable on `pigweed.dev <https://pigweed.dev>`_ |
| - ✅ |
| - ✅ |
| - ❌ |
| * - Auditable through source control |
| - ✅ |
| - ✅ |
| - ❌ |
| * - Archive of review comments and changes |
| - ✅ |
| - ✅ |
| - ❌ |
| * - Accessible to contributors |
| - ❌ |
| - ✅ |
| - ✅ |
| * - Extensive styling and formatting options |
| - ✅ |
| - ❌ |
| - ✅ |
| * - Easy sharing between Google and external contributors |
| - ✅ |
| - ✅ |
| - ❌ |
| |
| Integration |
| ----------- |
| .. admonition:: Goal |
| |
| SEED documents should seamlessly integrate with the rest of Pigweed's docs. |
| |
| As all of Pigweed's documentation is written using ReST, it becomes a natural |
| choice for SEEDs. The use of other formats requires additional scaffolding and |
| may not provide as seamless of an experience. |
| |
| Indexability |
| ------------ |
| .. admonition:: Goal |
| |
| Design decisions in SEEDs should be readily available for Pigweed users. |
| |
| `pigweed.dev <https://pigweed.dev>`_ has a search function allowing users to |
| search the site for Pigweed-related keywords. As SEEDs contain design discussion |
| and rationales, having them appear in these searches offers useful information |
| to users. |
| |
| The search function is provided by Pigweed's Sphinx build, so only documents |
| which exist as part of that (ReST / Markdown) are indexed. |
| |
| Auditability |
| ------------ |
| .. admonition:: Goal |
| |
| Changes to SEED documents should be reviewed and recorded. |
| |
| ReST and Markdown documents exist directly within Pigweed's source repository |
| after being submitted, requiring any further changes to go through a code |
| review process. |
| |
| Conversely, Google Docs may be edited by anyone with access, making them prone |
| to unintentional modification. |
| |
| Archive of discussions |
| ---------------------- |
| .. admonition:: Goal |
| |
| Discussions during the review of a SEED should be well-archived for |
| future reference. |
| |
| ReST and Markdown documentation are submitted through Gerrit and follow the |
| standard code review process. Review comments on the changes are saved in |
| Gerrit and are easily revisited. Incremental updates to the SEED during the |
| review process are saved as patch sets. |
| |
| Comments in Google Docs are more difficult to find once they are resolved, and |
| document changes do not exist as clearly-defined snapshots, making the history |
| of a SEED harder to follow. |
| |
| Accessibility |
| ------------- |
| .. admonition:: Goal |
| |
| SEEDs should be easy for contributors to write. |
| |
| Both Markdown and Google Docs are easy to write, familiar to many, and have |
| extensive tooling available. SEED documents can be written outside of the |
| Pigweed ecosystem using authors' preferred tools. |
| |
| ReST, on the other hand, is an unfamiliar and occasionally strange format, and |
| its usage for SEEDs is heavily tied to Pigweed's documentation build. Authors |
| are required to set up and constantly re-run this build, slowing iteration. |
| |
| Format and styling |
| ------------------ |
| .. admonition:: Goal |
| |
| SEED authors should have options for formatting various kinds of information |
| and data in their proposals. |
| |
| Markdown intentionally only offers limited control over document formatting, |
| whereas ReST has a wide selection of directives and Google Docs functions as a |
| traditional WYSIWYG editor, making them far more flexible. |
| |
| Sharing between Google and non-Google |
| ------------------------------------- |
| .. admonition:: Goal |
| |
| Both Google and non-Google contributors should easily be able to write and |
| review SEEDs. |
| |
| Due to security and legal concerns, managing ownership of Google Docs between |
| internal and external contributors is nontrivial. |
| |
| Text documentation formats like Markdown and ReST live within the Pigweed |
| repository, and as such follow the standard code contribution process. |