Adding and Tracking Proposals - magma/magma GitHub Wiki

Proposals Process

This document describes the process by which interested parties may propose changes to the Magma project. Proposals can be any size and cover any topic, e.g. process updates or architectural changes.

To start, consider skimming the existing Magma project proposals.

Overview

The current version of mermaid used by Github has a bug which does not support bottom-to-top sub-diagrams well.

graph TD
    Start[Contributer creates Issue with tag `type: proposal`] --> TSC["Public discussion with TSC. 1)"]
    TSC --> result[Documentation of the discussion result on the issue.]
    result --> void{ }

    void -->|accepted| accepted[Label issue with `status: accepted`]
    void -->|withdrawn| withdrawn[Label issue with `status: withdrawn`]
    void -->|rejected| rejected[Label issue with `status: rejected`]

    accepted --> close[Close the issue]
    withdrawn --> close
    rejected --> close

    subgraph Iteration
        %%{`direction BT`}%%
        doc -->refinement["Developer provides additional information 2)"]
        refinement --> feedback["Await reaction 3)"]
    end

    void -->|design doc| doc[Label issue with `status: needs design doc`]
    feedback --> TSC

With the following footnotes:

  1. Communication channels can be:
  2. Additional information can be in the for of:
    • a design document,
    • revision to design document,
    • further community discussion,
    • proposer response on the issue.
  3. The reaction may include
    • PR merge of new or updated design document,
    • reply on Github Issue by proposer
    • community comment on Github Issue

Acceptance

To be accepted, proposals must receive a majority vote from the TSC (these votes occur in TSC discussion in any of TSC Meetings (recorded), #governance-tsc slack channel, or [email protected] email group).

Tracking

Proposals are tracked as GitHub Issues, using the type: proposal label. Note that once resolved (proposal: accepted, proposal: withdrawn or proposal: rejectd), the associated Proposal GitHub issue is closed but remains discoverable in order to document the conclusion.

The #proposals Slack channel receives notifications when new proposals are created.

Submit a proposal

Submit an Issue

Submit a GitHub Issue following the "Proposal" template. The proposal contents should be clear and concise. Aim for a "one-pager" style. Some more complex proposals may merit a Design Doc (either by determination of the proposer, or as requested by the Magma TSC). Design docs if authored are submitted by Pull Request (PR) to docs/readmes/proposals, the PR description should reference the parent Proposal GitHub Issue for tracking purposes. Review of the design doc PR should be restricted to grammar, formatting, and the like - not the contents of the design doc. Content oriented discussion should instead happen on the associated proposal GH Issue (for tracking).

In many cases, the TSC will delegate their decision to one of the approvers teams. To expedite this process, you can label your proposal with the applicable component, which will help the TSC identify domain experts.

Receive feedback

The TSC, and relevant project maintainers, will discuss the proposal and make comments on the Issue. One of four outcomes will be communicated via labels

If your proposal is accepted, ensure actionable next-steps have been outlined and initiated.

Optional: needs design doc

If your proposal is labeled as needing a design doc, this means your proposal is nominally accepted, but needs to progress from the one-pager GitHub Issue into a fleshed-out design.

This design doc can start as e.g. a Google Doc or Quip Doc, but needs to eventually make its way into a pull request to add it to the project's Docusaurus.

When writing your design doc, consider following this standardized design doc template.

Resolution

A proposal Issue will be closed when no further discussion is needed. This occurs after one of the following

  • Acceptance, rejection, or withdrawal of the Issue
  • Acceptance of a requested design doc

Conclusion

Please direct process-related questions to the #governance-tsc Slack channel.