From 9211516165d53562e9d17760509d19221a23f8e4 Mon Sep 17 00:00:00 2001 From: Christopher Hein Date: Thu, 22 Oct 2020 11:06:37 -0700 Subject: [PATCH] adds proposals directory so we document our design (#2) Signed-off-by: Chris Hein --- proposals/YYYYMMDD-template.md | 252 +++++++++++++++++++++++++++++++++ 1 file changed, 252 insertions(+) create mode 100644 proposals/YYYYMMDD-template.md diff --git a/proposals/YYYYMMDD-template.md b/proposals/YYYYMMDD-template.md new file mode 100644 index 00000000..6c8495c0 --- /dev/null +++ b/proposals/YYYYMMDD-template.md @@ -0,0 +1,252 @@ +--- +title: Proposal Template +authors: + - "@janedoe" +reviewers: + - "@janedoe" +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](/proposals/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) + - [Security Model](#security-model) + - [Risks and Mitigations](#risks-and-mitigations) + - [Alternatives](#alternatives) + - [Upgrade Strategy](#upgrade-strategy) + - [Additional Details](#additional-details) + - [Test Plan [optional]](#test-plan-optional) + - [Graduation Criteria [optional]](#graduation-criteria-optional) + - [Version Skew Strategy [optional]](#version-skew-strategy-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 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 FR and NFR notation is intended to be used as cross-references across a CAEP. + +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. + +### Security Model + +Document the intended security model for the proposal, including implications +on the Kubernetes RBAC model. Questions you may want to answer include: + +* Does this proposal implement security controls or require the need to do so? + * If so, consider describing the different roles and permissions with tables. +* Are their adequate security warnings where appropriate (see https://adam.shostack.org/ReederEtAl_NEATatMicrosoft.pdf for guidance). +* Are regex expressions going to be used, and are their appropriate defenses against DOS. +* Is any sensitive data being stored in a secret, and only exists for as long as necessary? + +### 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] + +**Note:** *Section not required until targeted at a release.* + +Consider the following in developing a test plan for this enhancement: +- Will there be e2e and integration tests, in addition to unit tests? +- How will it be tested in isolation vs with other components? + +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 (eventually with coverage expectations). +Please adhere to the [Kubernetes testing guidelines][testing-guidelines] when drafting this test plan. + +[testing-guidelines]: https://git.k8s.io/community/contributors/devel/sig-testing/testing.md + +### Graduation Criteria [optional] + +**Note:** *Section not required until targeted at a release.* + +Define graduation milestones. + +These may be defined in terms of API maturity, or as something else. Initial proposal should keep +this high-level with a focus on what signals will be looked at to determine graduation. + +Consider the following in developing the graduation criteria for this enhancement: +- [Maturity levels (`alpha`, `beta`, `stable`)][maturity-levels] +- [Deprecation policy][deprecation-policy] + +Clearly define what graduation means by either linking to the [API doc definition](https://kubernetes.io/docs/concepts/overview/kubernetes-api/#api-versioning), +or by redefining what graduation means. + +In general, we try to use the same stages (alpha, beta, GA), regardless how the functionality is accessed. + +[maturity-levels]: https://git.k8s.io/community/contributors/devel/sig-architecture/api_changes.md#alpha-beta-and-stable-versions +[deprecation-policy]: https://kubernetes.io/docs/reference/using-api/deprecation-policy/ + +### Version Skew Strategy [optional] + +If applicable, how will the component handle version skew with other components? What are the guarantees? Make sure +this is in the test plan. + +Consider the following in developing a version skew strategy for this enhancement: +- Does this enhancement involve coordinating behavior in the control plane and in the kubelet? How does an n-2 kubelet without this feature available behave when this feature is used? +- Will any other components on the node change? For example, changes to CSI, CRI or CNI may require updating that component before the kubelet. + +## 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 + + +[community meeting]: https://docs.google.com/document/d/1Ys-DOR5UsgbMEeciuG0HOgDQc8kZsaWIWJeKJ1-UfbY