| .. _seed-0001: |
| |
| ====================== |
| 0001: The SEED Process |
| ====================== |
| |
| .. card:: |
| :fas:`seedling` SEED-0001: :ref:`The SEED Process<seed-0001>` |
| |
| :octicon:`comment-discussion` Status: |
| :bdg-secondary-line:`Open for Comments` |
| :octicon:`chevron-right` |
| :bdg-secondary-line:`Last Call` |
| :octicon:`chevron-right` |
| :bdg-primary:`Accepted` |
| :octicon:`kebab-horizontal` |
| :bdg-secondary-line:`Rejected` |
| |
| :octicon:`calendar` Proposal Date: 2022-10-31 |
| |
| :octicon:`code-review` CL: `pwrev/116577 <https://pigweed-review.googlesource.com/c/pigweed/pigweed/+/116577>`_ |
| |
| ------- |
| 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-getting-started` guide. |
| |
| #. Copy the `SEED template <0002-template>`_ to create the RST file for your |
| SEED. As you don't yet have a SEED number, use XXXX as a placeholder, |
| followed by the lowercase title of the proposal, with words separated by |
| hyphens. |
| |
| .. code-block:: sh |
| |
| cp seed/0002-template.rst seed/XXXX-pw_rpc-over-smoke-signals.rst |
| |
| #. Push up the template to Gerrit, marking it as a Work-In-Progress change. |
| From here, you may fill the template out with the content of your proposal |
| at your convenience. |
| |
| #. At any point, you may claim a SEED number by opening the |
| `SEED index`_ and taking the next available number by inserting |
| a row into the ``toctree`` table. Link the entry to the WIP change for your |
| SEED. |
| |
| .. _SEED index: https://cs.opensource.google/pigweed/pigweed/+/main:seed/0000-index.rst |
| |
| .. code-block:: rst |
| |
| .. toctree:: |
| |
| 0001-the-seed-process |
| ... |
| 5308-some-other-seed |
| 5309: pw_rpc Over Smoke Signals<https://pigweed-review.googlesource.com/c/pigweed/pigweed/+/116577> |
| |
| #. Commit your change to the index (and nothing else) with the commit message |
| ``SEED-xxxx: Claim SEED number``. |
| |
| .. code-block:: sh |
| |
| git add seed/0000-index.rst |
| git commit -m "SEED-5309: Claim SEED number" |
| |
| #. Push up a changelist (CL) to Gerrit following the :ref:`docs-contributing` |
| guide and add GWSQ as a reviewer. Set ``Pigweed-Auto-Submit`` to +1. |
| |
| .. image:: 0001-the-seed-process/seed-index-gerrit.png |
| |
| #. Once your CL has been reviewed and submitted, the SEED number belongs to you. |
| Update your document's template and filename with this number. |
| |
| #. 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. |
| |
| #. Engage with reviewers to iterate on your proposal through its comment period. |
| |
| #. When a tentative decision has been reached, a Pigweed team member 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, a Pigweed team member will |
| sign off on the CL with a +2 vote, allowing it to be submitted. Update the |
| reference in the SEED index with the link to your document and submit the CL. |
| |
| .. code-block:: rst |
| |
| .. toctree:: |
| |
| 0001-the-seed-process |
| ... |
| 5308-some-other-seed |
| 5309-pw_rpc-over-smoke-signals |
| |
| -------------- |
| 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. |
| |
| :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 Pigweed's review committee when they feel there has been |
| sufficient discussion on the tradeoffs of the proposal to do so. |
| - Transition is triggered manually by a member of the Pigweed team, 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. |