From 3aa9e5654b21a4ded789635f5b34f39b4f90b981 Mon Sep 17 00:00:00 2001 From: Siyu Wang Date: Mon, 22 Aug 2022 19:35:04 +0800 Subject: [PATCH] Add proposal template Signed-off-by: Siyu Wang --- docs/proposals/YYYYMMDD-template.md | 191 ++++++++++++++++++++++++++++ 1 file changed, 191 insertions(+) create mode 100644 docs/proposals/YYYYMMDD-template.md diff --git a/docs/proposals/YYYYMMDD-template.md b/docs/proposals/YYYYMMDD-template.md new file mode 100644 index 00000000..ab29d0cb --- /dev/null +++ b/docs/proposals/YYYYMMDD-template.md @@ -0,0 +1,191 @@ +--- +title: Proposal Template +authors: + - "@XXX" +reviewers: + - "@YYY" +creation-date: yyyy-mm-dd +last-updated: yyyy-mm-dd +status: provisional|experimental|implementable|implemented|deferred|rejected|withdrawn|replaced +see-also: + - "/docs/proposals/20190101-we-heard-you-like-proposals.md" + - "/docs/proposals/20190102-everyone-gets-a-proposal.md" +replaces: + - "/docs/proposals/20181231-replaced-proposal.md" +superseded-by: + - "/docs/proposals/20190104-superceding-proposal.md" +--- + +# Title + +- Keep it simple and descriptive. +- A good title can help communicate what the proposal is and should be considered as part of any review. + + +To get started with this template: +1. **Make a copy of this template.** + Copy this template into `docs/enhacements` and name it `YYYYMMDD-my-title.md`, where `YYYYMMDD` is the date the proposal was first drafted. +1. **Fill out the required sections.** +1. **Create a PR.** + Aim for single topic PRs to keep discussions focused. + If you disagree with what is already in a document, open a new PR with suggested changes. + +The canonical place for the latest set of instructions (and the likely source of this file) is [here](./YYYYMMDD-template.md). + +The `Metadata` section above is intended to support the creation of tooling around the proposal process. +This will be a YAML section that is fenced as a code block. +See the proposal process for details on each of these items. + + + +## Table of Contents + +A table of contents is helpful for quickly jumping to sections of a proposal and for highlighting +any additional information provided beyond the standard proposal template. +[Tools for generating](https://github.com/ekalinin/github-markdown-toc) a table of contents from markdown are available. + +- [Title](#title) + - [Table of Contents](#table-of-contents) + - [Glossary](#glossary) + - [Summary](#summary) + - [Motivation](#motivation) + - [Goals](#goals) + - [Non-Goals/Future Work](#non-goalsfuture-work) + - [Proposal](#proposal) + - [User Stories](#user-stories) + - [Story 1](#story-1) + - [Story 2](#story-2) + - [Requirements (Optional)](#requirements-optional) + - [Functional Requirements](#functional-requirements) + - [FR1](#fr1) + - [FR2](#fr2) + - [Non-Functional Requirements](#non-functional-requirements) + - [NFR1](#nfr1) + - [NFR2](#nfr2) + - [Implementation Details/Notes/Constraints](#implementation-detailsnotesconstraints) + - [Risks and Mitigations](#risks-and-mitigations) + - [Alternatives](#alternatives) + - [Upgrade Strategy](#upgrade-strategy) + - [Additional Details](#additional-details) + - [Test Plan [optional]](#test-plan-optional) + - [Implementation History](#implementation-history) + +## Glossary + +Refer to the [Cluster API Book Glossary](https://cluster-api.sigs.k8s.io/reference/glossary.html). + +If this proposal adds new terms, or defines some, make the changes to the book's glossary when in PR stage. + +## Summary + +The `Summary` section is incredibly important for producing high quality user-focused documentation such as release notes or a development roadmap. +It should be possible to collect this information before implementation begins in order to avoid requiring implementors to split their attention between writing release notes and implementing the feature itself. + +A good summary is probably at least a paragraph in length. + +## Motivation + +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. +- The motivation section can optionally provide links to [experience reports](https://github.com/golang/go/wiki/ExperienceReports) +to demonstrate the interest in a proposal within the wider Kubernetes community. + +### Goals + +- List the specific high-level goals of the proposal. +- How will we know that this has succeeded? + +### Non-Goals/Future Work + +- What high-levels are out of scope for this proposal? +- Listing non-goals helps to focus discussion and make progress. + +## Proposal + +This is where we get down to the nitty gritty of what the proposal actually is. + +- What is the plan for implementing this feature? +- What data model changes, additions, or removals are required? +- Provide a scenario, or example. +- Use diagrams to communicate concepts, flows of execution, and states. + +[PlantUML](http://plantuml.com) is the preferred tool to generate diagrams, +place your `.plantuml` files under `images/` and run `make diagrams` from the docs folder. + +### User Stories + +- Detail the things that people will be able to do if this proposal 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. + +#### Story 1 + +#### Story 2 + +### Requirements (Optional) + +Some authors may wish to use requirements in addition to user stories. +Technical requirements should be derived from user stories, and provide a trace from +use case to design, implementation and test case. Requirements can be prioritised +using the MoSCoW (MUST, SHOULD, COULD, WON'T) criteria. + +The difference between goals and requirements is that between an executive summary +and the body of a document. Each requirement should be in support of a goal, +but narrowly scoped in a way that is verifiable or ideally - testable. + +#### Functional Requirements + +Functional requirements are the properties that this design should include. + +##### FR1 + +##### FR2 + +#### Non-Functional Requirements + +Non-functional requirements are user expectations of the solution. Include +considerations for performance, reliability and security. + +##### NFR1 + +##### NFR2 + +### Implementation Details/Notes/Constraints + +- What are some important details that didn't come across above. +- What are the caveats to the implementation? +- Go in to as much detail as necessary here. +- Talk about core concepts and how they releate. + +### Risks and Mitigations + +- What are the risks of this proposal and how do we mitigate? Think broadly. +- How will UX be reviewed and by whom? +- How will security be reviewed and by whom? +- Consider including folks that also work outside the SIG or subproject. + +## Alternatives + +The `Alternatives` section is used to highlight and record other possible approaches to delivering the value proposed by a proposal. + +## Upgrade Strategy + +If applicable, how will the component be upgraded? Make sure this is in the test plan. + +Consider the following in developing an upgrade strategy for this enhancement: +- What changes (in invocations, configurations, API use, etc.) is an existing cluster required to make on upgrade in order to keep previous behavior? +- What changes (in invocations, configurations, API use, etc.) is an existing cluster required to make on upgrade in order to make use of the enhancement? + +## Additional Details + +### Test Plan [optional] + +## Implementation History + +- [ ] MM/DD/YYYY: Proposed idea in an issue or [community meeting] +- [ ] MM/DD/YYYY: Compile a Google Doc following the CAEP template (link here) +- [ ] MM/DD/YYYY: First round of feedback from community +- [ ] MM/DD/YYYY: Present proposal at a [community meeting] +- [ ] MM/DD/YYYY: Open proposal PR +