Skip to content

Latest commit

 

History

History
96 lines (60 loc) · 4.72 KB

0001-template.md

File metadata and controls

96 lines (60 loc) · 4.72 KB

RFC title

Brief, self-describing title of the RFC.

Summary

One paragraph explanation of the feature. Describe the "why" and feature benefit.

Motivation

Reflect the will of the PRD (product requirements document). If the PRD is a linkable artifact, include the link here. If not, summarize the product requirement in your own words. Describe the delta of this change.

Be sure to include:

  • What are the hypotheses behind how this change meets the needs of a PRD?
  • What is the expected outcome or outcomes and what are the exit conditions along the way? Include assessment criteria and ideally measurements that will either verify this hypothesis or yield opportunities to halt and abandon the implementation.
  • What are we optimizing for in this particular solution? Reflect on alternatives in a later section.
  • What use cases does it support?

Detailed design

In general:

  • Be specific. This document is meant to share intent to your colleagues. Share what you believe you will actually do.
  • Be decisive. No maybes. Any uncertainty can be captured in the unresolved questions section at the end.
  • Provide design contex so that we can align on and commit to a technical design.

Beyond the design of the change itself, also include details around:

  • Security implications
  • Performance
  • The impact of this change on other components or systems
  • Dissect edge cases with examples

Evergreen, wide-sweeping Details

Evergreen details are hypothesized to be true for the lifetime of this component or system. They are also hard to pinpoint a location in a spec as they are too widesweeping.

Evergreen details are included directly in the RFC in this section.

Ephemeral details

Ephemeral details must live in the spec so that they can evolve over time.

In this section, link to one or more lines of code in committed GitHub code or one or more lines within a PR or PR draft.

When in doubt, "the spec" can be a block comment in source code, but there are a few conventions for our existing systems:

In proof systems-related projects:

  • The spec is inline comments that are generated by using cargo-spec

For Mina Daemon:

For SnarkyJS and other zkApps-related projects:

  • The spec is inline comments. Prefer cargo-spec format, so we can extract them later.

Test plan and functional requirements

  1. Testing goals and objectives:
    • Specify the overall goals and objectives of testing for the proposed feature or project. This can help set the expectations for testing efforts once the implementation details are finalized.
  2. Testing approach:
    • Outline the general approach or strategy for testing that will be followed. This can include mentioning the types of testing to be performed (e.g., unit testing, integration testing, performance testing) and any specific methodologies or tools that will be utilized.
  3. Testing scope:
    • Define the scope of testing by identifying the key areas or functionalities that will be covered by testing efforts.
  4. Testing requirements:
    • Specify any specific testing requirements that need to be considered, such as compliance requirements, security testing, or specific user scenarios to be tested.
  5. Testing resources:
    • Identify the resources required for testing, such as testing environments, test data, or any additional tools or infrastructure needed for effective testing.

Drawbacks

Why should we not do this?

Rationale and alternatives

  • Why is this design the best in the space of possible designs?
  • What other designs have been considered and what is the rationale for not choosing them?
  • What is the impact of not doing this?

Prior art

Discuss prior art, both the good and the bad, in relation to this proposal.

Prior art is any evidence that your feature (invention, change, proposal) is already known.

Think about the lessons from other blockchain projects or similar updates and provide readers of your RFC with a fuller picture. If there is no prior art, that is fine. Your ideas are interesting whether they are new or adapted from another source.

Unresolved questions

  • What parts of the design do you expect to resolve through the RFC process before this RFC gets merged?
  • What parts of the design do you expect to resolve through the implementation of this feature before merge?
  • What related issues do you consider out of scope for this RFC that could be addressed in the future independently of the solution that comes out of this RFC?