This is the title of your proposal. Keep it short, simple, and descriptive. A good title can help communicate what the proposal is and should be considered as part of any review.
The Summary section is incredibly important for producing high quality
user-focused documentation such as release notes or a development roadmap.
A good summary is probably at least a paragraph in length.
This section is for explicitly listing the motivation, goals and non-goals of this proposal. Describe why the change is important and the benefits to users.
List the specific goals of the proposal. How will we know that this has succeeded?
What is out of scope for this proposal? Listing non-goals helps to focus discussion and make progress.
This is where we get down to the specifics of what the enhancement actually is. This should have enough detail that reviewers can understand exactly what you're proposing, but should not include things like API designs or implementation. What is the desired outcome and how do we measure success?. The "Design Details" section below is for the real nitty-gritty.
Detail the things that people will be able to do if this is implemented. Include as much detail as possible so that people can understand the "how" of the system. The goal here is to make this feel real for users without getting bogged down.
What are the caveats to the proposal? What are some important details that didn't come across above? Go in to as much detail as necessary here. This might be a good place to talk about core concepts and how they relate.
What are the risks of this proposal, and how do we mitigate? Think broadly. For example, consider both security and how this will impact the ecosystem.
This section should contain enough information that the specifics of your change are understandable. This may include API specs (though not always required) or even code snippets. If there's any ambiguity about HOW your proposal will be implemented, this is the place to discuss them.
Consider the following in developing a test plan for this enhancement:
- Will there be e2e tests, in addition to unit tests?
No need to outline all of the test cases, just the general strategy. Anything that would count as tricky in the implementation, and anything particularly challenging to test, should be called out.
All code is expected to have adequate tests.
If applicable, how will the component be upgraded and downgraded? Make sure this is in the test plan.
How will the component handle version skew with other components? What are the guarantees? Make sure this is in the test plan.
Major milestones in the life cycle of a proposal should be tracked in Implementation History.
Why should this enhancement not be implemented?
What other approaches did you consider, and why did you rule them out? These do not need to be as detailed as the proposal, but should include enough information to express the idea and why it was not acceptable.
Use this section if you need things from the project. Examples include a new repo requested, and/or testing infrastructure.
Listing these here allows the community to get the process for these resources started right away.