|
| 1 | +<!-- |
| 2 | +How to use this template: |
| 3 | +
|
| 4 | +- Make a copy of this file in the docs/proposals/ directory |
| 5 | +- Set the name of the file to contain the next logical number and the name of the feature |
| 6 | +- Fill out at least the Status, Motivation and Goals/Non-Goals fields. |
| 7 | +- Open a PR to green-reviews-tooling |
| 8 | +- Merge early and iterate |
| 9 | +
|
| 10 | +For more tips see the Contributing docs: https://github.com/cncf-tags/green-reviews-tooling/blob/main/CONTRIBUTING.md#proposals |
| 11 | +--> |
| 12 | + |
| 13 | +# Short, descriptive title |
| 14 | + |
| 15 | +<!-- |
| 16 | +Keep the title short, simple, and descriptive. A good |
| 17 | +title can help communicate what the proposal is and should be |
| 18 | +considered as part of any review. |
| 19 | +--> |
| 20 | + |
| 21 | +## Authors |
| 22 | + |
| 23 | +<!-- |
| 24 | +Who is responsible for this proposal? Who can answer questions? |
| 25 | +--> |
| 26 | + |
| 27 | +## Status |
| 28 | + |
| 29 | +<!-- |
| 30 | +Must be one of provisional, implementable, implemented, deferred, |
| 31 | +rejected, withdrawn, or replaced. |
| 32 | +--> |
| 33 | + |
| 34 | + |
| 35 | +<!-- |
| 36 | +The headings here are just starting points, add more as makes sense for what you |
| 37 | +are proposing. |
| 38 | +--> |
| 39 | +## Table of Contents |
| 40 | +<!-- toc --> |
| 41 | +- [Short, descriptive title](#short-descriptive-title) |
| 42 | + - [Authors](#authors) |
| 43 | + - [Status](#status) |
| 44 | + - [Table of Contents](#table-of-contents) |
| 45 | + - [Summary](#summary) |
| 46 | + - [Motivation](#motivation) |
| 47 | + - [Goals](#goals) |
| 48 | + - [Non-Goals](#non-goals) |
| 49 | + - [Linked Docs](#linked-docs) |
| 50 | + - [Proposal](#proposal) |
| 51 | + - [User Stories (Optional)](#user-stories-optional) |
| 52 | + - [Story 1](#story-1) |
| 53 | + - [Story 2](#story-2) |
| 54 | + - [Notes/Constraints/Caveats (Optional)](#notesconstraintscaveats-optional) |
| 55 | + - [Risks and Mitigations](#risks-and-mitigations) |
| 56 | + - [Design Details](#design-details) |
| 57 | + - [Graduation Criteria (Optional)](#graduation-criteria-optional) |
| 58 | + - [Drawbacks (Optional)](#drawbacks-optional) |
| 59 | + - [Alternatives](#alternatives) |
| 60 | + - [Infrastructure Needed (Optional)](#infrastructure-needed-optional) |
| 61 | +<!-- /toc --> |
| 62 | + |
| 63 | +## Summary |
| 64 | + |
| 65 | +<!-- |
| 66 | +A good summary is at least a paragraph in length and should be written with a wide audience |
| 67 | +in mind. |
| 68 | +
|
| 69 | +It should encompass the entire document, and serve as both future documentation |
| 70 | +and as a quick reference for people coming by to learn the proposal's purpose |
| 71 | +without reading the entire thing. |
| 72 | +
|
| 73 | +Both in this section and below, follow the guidelines of the [documentation |
| 74 | +style guide]. In particular, wrap lines to a reasonable length, to make it |
| 75 | +easier for reviewers to cite specific portions, and to minimize diff churn on |
| 76 | +updates. |
| 77 | +
|
| 78 | +[documentation style guide]: https://github.com/kubernetes/community/blob/master/contributors/guide/style-guide.md |
| 79 | +--> |
| 80 | + |
| 81 | +## Motivation |
| 82 | + |
| 83 | +<!-- |
| 84 | +This section is for explicitly listing the motivation, goals and non-goals of |
| 85 | +this proposal. Describe why the change is important, how it fits into the project's |
| 86 | +goals and the benefits to users. |
| 87 | +
|
| 88 | +It is helpful to frame this to answer the question: "What is the problem this proposal |
| 89 | +is trying to solve?" |
| 90 | +--> |
| 91 | + |
| 92 | +### Goals |
| 93 | + |
| 94 | +<!-- |
| 95 | +List the specific goals of the proposal. What is it trying to achieve? How will we |
| 96 | +know that this has succeeded? |
| 97 | +--> |
| 98 | + |
| 99 | +### Non-Goals |
| 100 | + |
| 101 | +<!-- |
| 102 | +What is out of scope for this proposal? Listing non-goals helps to focus discussion |
| 103 | +and make progress. |
| 104 | +
|
| 105 | +It is important to remember that non-goals are still equally important things |
| 106 | +which will be dealt with one day but are not things which need to be dealt with immediately |
| 107 | +within the scope of this work. This helps make sure everyone is crystal clear on the outcomes. |
| 108 | +--> |
| 109 | + |
| 110 | +### Linked Docs |
| 111 | + |
| 112 | +<!-- |
| 113 | +Provide links to previous discussions, Slack threads, motivation issues or any other document |
| 114 | +with context. It is really helpful to provide a "source of truth" for the work |
| 115 | +so that people aren't searching all over the place for lost context. |
| 116 | +--> |
| 117 | + |
| 118 | +## Proposal |
| 119 | + |
| 120 | +<!-- |
| 121 | +This is where we get down to the specifics of what the proposal actually is: |
| 122 | +outlining your solution to the problem described in the Motivation section. |
| 123 | +This should have enough detail that reviewers can understand exactly what |
| 124 | +you're proposing, but should not include things like API designs or |
| 125 | +implementation. The "Design Details" section below is for the real |
| 126 | +nitty-gritty. |
| 127 | +--> |
| 128 | + |
| 129 | +### User Stories (Optional) |
| 130 | + |
| 131 | +<!-- |
| 132 | +Detail the things that people will be able to do if this proposal is implemented. |
| 133 | +Include as much detail as possible so that people can understand the "how" of |
| 134 | +the system. The goal here is to make this feel real for users without getting |
| 135 | +bogged down. |
| 136 | +--> |
| 137 | + |
| 138 | +#### Story 1 |
| 139 | + |
| 140 | +#### Story 2 |
| 141 | + |
| 142 | +### Notes/Constraints/Caveats (Optional) |
| 143 | + |
| 144 | +<!-- |
| 145 | +What are the caveats to the proposal? |
| 146 | +What are some important details that didn't come across above? |
| 147 | +Go in to as much detail as necessary here. |
| 148 | +This might be a good place to talk about core concepts and how they relate. |
| 149 | +--> |
| 150 | + |
| 151 | +### Risks and Mitigations |
| 152 | + |
| 153 | +<!-- |
| 154 | +What are the risks of this proposal, and how do we mitigate? |
| 155 | +Think broadly. For example, consider how this will impact or be impacted |
| 156 | +by scaling to support more CNCF Projects. |
| 157 | +
|
| 158 | +How will this affect the benchmark tests, CNCF Project Maintainers, pipeline maintainers, etc? |
| 159 | +--> |
| 160 | + |
| 161 | +## Design Details |
| 162 | + |
| 163 | +<!-- |
| 164 | +This section should contain enough information that the specifics of your |
| 165 | +change are understandable. This may include manifests or workflow examples |
| 166 | +(though not always required) or even code snippets. If there's any ambiguity |
| 167 | +about HOW your proposal will be implemented, this is the place to discuss them. |
| 168 | +--> |
| 169 | + |
| 170 | +### Graduation Criteria (Optional) |
| 171 | + |
| 172 | +<!-- |
| 173 | +List criteria which would allow progression from one maturity level to another. |
| 174 | +eg. What needs to have been accomplished/demonstrated to move from Alpha to Beta. |
| 175 | +
|
| 176 | +If applicable, what is the milestone marker which will allow deprecation of the |
| 177 | +replaced capability? |
| 178 | +--> |
| 179 | + |
| 180 | +## Drawbacks (Optional) |
| 181 | + |
| 182 | +<!-- |
| 183 | +What other approaches did you consider, and why did you rule them out? These do |
| 184 | +not need to be as detailed as the proposal, but should include enough |
| 185 | +information to express the idea and why it was not acceptable. |
| 186 | +--> |
| 187 | + |
| 188 | +## Alternatives |
| 189 | + |
| 190 | +<!-- |
| 191 | +What other approaches did you consider, and why did you rule them out? These do |
| 192 | +not need to be as detailed as the proposal (pros and cons are fine), |
| 193 | +but should include enough information to express the idea and why it was not acceptable |
| 194 | +as well as illustrate why the final solution was selected. |
| 195 | +--> |
| 196 | + |
| 197 | +## Infrastructure Needed (Optional) |
| 198 | + |
| 199 | +<!-- |
| 200 | +Use this section if you need things from the project/SIG. Examples include a |
| 201 | +new subproject, repos requested, or GitHub details. Listing these here allows a |
| 202 | +SIG to get the process for these resources started right away. |
| 203 | +--> |
0 commit comments