0001: The SEED Process#
Pigweed AI summary: SEEDs are a formalized process for proposing, reviewing, and deciding on changes to the Pigweed project. This document provides an overview of the SEED process and outlines its goals, including increasing visibility of proposed changes, maintaining a public record of design decisions, and ensuring consistent API design. SEEDs go through several phases, including being open for comments, last call, acceptance, rejection, deprecation, or being superseded. SEED documents are written in ReST format and integrated with
Status: Open for Comments Last Call Accepted Rejected
Proposal Date: 2022-10-31
CL: pwrev/116577
Summary#
Pigweed AI summary: The SEED process is a collaborative effort by community stakeholders to propose and implement significant changes to Pigweed. This document provides an overview of the SEED process, while specific details on how to write and structure SEEDs can be found in the 0002: SEED Template.
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 0002: SEED Template.
Motivation#
Pigweed AI summary: The Pigweed project is growing and it's important to ensure that the team, users, and stakeholders are aligned on its future. The SEED process is a formalized way to propose, review, and ratify changes to Pigweed. Its goals include increasing visibility of proposed changes, maintaining a public record of design decisions, and ensuring consistent API design. Active SEEDs are discussed by the community through Gerrit code review comments and a SEEDs chatroom, with decisions ultimately made by a
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?#
Pigweed AI summary: Developers who wish to make a significant change to Pigweed should write a SEED. The definition of a "substantial" change may vary depending on the parts of Pigweed it affects and may change over time. Examples of substantial changes include adding a new top-level module, modifying a widely-used public API, and changing data interchange or storage protocols. Conversely, fixing typos, refactoring internal module code without public API changes, and adding minor parallel operations to existing APIs may not require a SE
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,
pwcommands, 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)vsRead(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#
Pigweed AI summary: This section provides a step-by-step guide on how to propose a new Pigweed RPC Over Smoke Signals protocol. It includes instructions on cloning the Pigweed repository, creating a SEED template, claiming a SEED number, committing changes to the index, pushing up a changelist to Gerrit, engaging with reviewers, and submitting the proposal for review. The section also outlines the Last Call phase and the final steps for submitting the proposal.
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 Getting Started guide.
Copy the SEED 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.
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
toctreetable. Link the entry to the WIP change for your SEED... 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.git add seed/0000-index.rst git commit -m "SEED-5309: Claim SEED number"
Push up a changelist (CL) to Gerrit following the Contributing guide and add GWSQ as a reviewer. Set
Pigweed-Auto-Submitto +1.
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 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.
.. toctree:: 0001-the-seed-process ... 5308-some-other-seed 5309-pw_rpc-over-smoke-signals
SEED documents#
Pigweed AI summary: SEED documents are ReST documents that are integrated with Pigweed's documentation and are located in the seed/ subdirectory of the Pigweed repository. The structure and format of SEED documents are outlined in 0002: SEED Template. The first 100 SEEDs are Meta-SEEDs, which are reserved for internal Pigweed usage and may be revised over time.
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 0002: SEED Template.
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.
The lifecycle of a SEED#
Pigweed AI summary: The lifecycle of a SEED proposal involves several phases, starting with the draft phase where it is not yet ready for comments, followed by the open for comments phase where interested parties can provide feedback and discuss the proposal. The last call phase is when a tentative decision has been made, but commenters may still raise final objections. If the proposal is accepted, it is ratified and ready for implementation, but if it is rejected, it is submitted into the Pigweed repository for future reference. If the proposal
A SEED proposal undergoes several phases between first being published and a final decision.
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.
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.
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.
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.
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.
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.
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#
Pigweed AI summary: The document discusses three different documentation formats for SEEDs: ReST, Google Docs, and Markdown. Based on evaluated criteria, ReST documents provide the best overall SEED experience, although there are issues with contributor tooling. The document also details the main criteria evaluated for each format, including straightforward integration with existing docs, indexability on pigweed.dev, auditability through source control, archive of review comments and changes, accessibility to contributors, extensive styling and formatting options, and easy sharing between Google
Document format#
Pigweed AI summary: The SEEDs documentation format has three options: ReST, Google Docs, and Markdown. ReST is the best option based on evaluated criteria, but it has issues with contributor tooling. ReST documents integrate well with Pigweed's existing documentation, while Google Docs and Markdown require additional scaffolding. ReST and Markdown documents are auditable through source control, while Google Docs may be edited by anyone with access. ReST and Markdown also provide an archive of review comments and changes, while Google
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#
Pigweed AI summary: ReST documents provide the best overall SEED experience based on evaluated criteria, although there are issues with contributor tooling that may require additional investment from the Pigweed team. The table provided details the main criteria evaluated for each format, with ReST scoring well in most categories except for accessibility to contributors. Markdown and Google Docs also had their strengths and weaknesses, but ReST was deemed the best option overall.
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.
Criterion |
ReST |
Markdown |
Google Docs |
|---|---|---|---|
Straightforward integration with existing docs |
✅ |
❌ |
❌ |
Indexable on 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#
Pigweed AI summary: The goal of SEED documents is to integrate smoothly with the rest of Pigweed's documentation. Since all of Pigweed's documentation is written using ReST, it is the natural choice for SEEDs as other formats would require additional scaffolding and may not provide as seamless of an experience.
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#
Pigweed AI summary: The goal of SEEDs in Pigweed is to make design decisions readily available to users. Pigweed's website has a search function that allows users to search for Pigweed-related keywords, including SEEDs which contain design discussions and rationales. However, only documents that exist as part of Pigweed's Sphinx build are indexed.
Goal
Design decisions in SEEDs should be readily available for Pigweed users.
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#
Pigweed AI summary: The section titled "Auditability" discusses the importance of reviewing and recording changes made to SEED documents. It highlights the difference between ReST and Markdown documents, which require a code review process for any further changes, and Google Docs, which can be edited by anyone with access and are therefore more prone to unintentional modification.
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#
Pigweed AI summary: This paragraph discusses the importance of well-archived discussions during the review of a SEED. ReST and Markdown documentation are submitted through Gerrit and are easily revisited, with review comments saved as patch sets. However, comments in Google Docs are harder to find once resolved and document changes are not clearly-defined snapshots, making it difficult to follow the history of a SEED.
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#
Pigweed AI summary: The goal of SEEDs is to make it easy for contributors to write. Markdown and Google Docs are popular and user-friendly tools that have extensive tooling available. SEED documents can be written using authors' preferred tools outside of the Pigweed ecosystem. However, ReST is an unfamiliar and occasionally strange format that is heavily tied to Pigweed's documentation build, requiring authors to constantly re-run the build and slowing down the iteration process.
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#
Pigweed AI summary: The "Format and styling" section discusses the need for SEED authors to have options for formatting information and data in their proposals. While Markdown offers limited control over formatting, ReST provides a wider selection of directives and Google Docs functions as a traditional WYSIWYG editor, making them more flexible.
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.