Add proposal template
Signed-off-by: Siyu Wang <FillZpp.pub@gmail.com>
This commit is contained in:
Siyu Wang
parent
2d80e387fa
commit
3aa9e5654b
|
|
@ -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.
|
||||
|
||||
<!-- BEGIN Remove before PR -->
|
||||
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.
|
||||
|
||||
<!-- END Remove before PR -->
|
||||
|
||||
## 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
|
||||
|
||||
Loading…
Reference in New Issue