Skip to content

Latest commit

 

History

History
44 lines (33 loc) · 2.36 KB

0000-template.md

File metadata and controls

44 lines (33 loc) · 2.36 KB
Raw
RFC Title Start PR
<blank>
TODO_TITLE
TODO_START
<blank>

TODO_TITLE

SEE README.md for how to submit a new RFC, and 0001-using_rfcs.md for why we are using an RFC process. Delete this line when done.

Summary

This is a one paragraph explanation of the issue and the proposal.

Motivation

This section details why we are doing something, what use cases it supports, and what we expect the outcome to be.

Guide Implementation

This is a high level overview of the process. In this section, explain the proposal as if it was already used at your company and you were teaching it to a new engineer. That means you're probably including

  • Introduction of new named concepts
  • Explain things in terms of examples
  • Explain the impact and how you want engineers to approach the feature and its goals
  • If applicable, provide sample errors / warnings / or migration guidance
  • If applicable, describe the differences required teaching this to new engineers vs existing engineers

Reference Implementation

This section provides space for deep technical details as required in the RFC. You need to hit on the following points in your reference implementation:

  • It's interaction with other features / infrastructure
  • It is reasonably clear how this would be implemented
  • Corner cases are addressed through example You can (and should) expand on the examples you used in the Guide Implementation and provide additional context.

Drawbacks

You should explain why we wouldn't do this. There is a cost associated with these changes, and while there wouldn't be an RFC if the benefits didn't outweigh the drawbacks, your readers might not know all of the tradeoffs being made.

Rationale / Alternatives

You need to answer why this design is the right design. To do so, you need to understand all of the possible alternatives. You should list alternate designs and ideas and why they weren't considered for the solution. This ensures due diligence has been done on the proposal.

Unresolved Questions

You should gather any open questions and either list them in the document (folks often use markdown quoting) or add them to this section at the end of the document. If you want to mark unresolved options inline

Open Question: this is an open question

Is the common format used. The quote and bold combination (plus its indent) makes it easy to spot when reading through the document.