forked from kubewharf/katalyst-core
206 lines
7.3 KiB
Markdown
206 lines
7.3 KiB
Markdown
---
|
|
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/proposals` 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)
|
|
- [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)
|
|
- [Design Overview [Optional]](#design-overview-optional)
|
|
- [API [Optional]](#api-optional)
|
|
- [Design Details](#design-details)
|
|
- [Non-Functional Design [Optional]](#non-functional-design-optional)
|
|
- [Alternatives](#alternatives)
|
|
- [Additional Details](#additional-details)
|
|
- [Test Plan [optional]](#test-plan-optional)
|
|
- [Implementation History](#implementation-history)
|
|
|
|
## 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 Katalyst 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
|
|
|
|
### Design Overview [Optional]
|
|
|
|
This section is used to describe the overall design of the proposal. For example,
|
|
|
|
- The architecture of the system.
|
|
- What components of the system are relevant to this proposal?
|
|
- How do these components communicate with each other?
|
|
|
|
### API [Optional]
|
|
|
|
This section is used to explain the design related to API. For example,
|
|
|
|
- Addition, deletion and modification of CRDs.
|
|
- Addition, deletion and modification of labels, annotations, and finalizers.
|
|
- Addition, deletion and modification of resource keys.
|
|
|
|
### Design Details
|
|
|
|
- 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 relate.
|
|
|
|
## Non-Functional Design [Optional]
|
|
|
|
This section is used to describe non-functional design. For example,
|
|
|
|
- Performance
|
|
- Observability
|
|
- Scalability
|
|
- Extensibility
|
|
- Upgrade strategy
|
|
- Risks and mitigations
|
|
|
|
## Alternatives
|
|
|
|
The `Alternatives` section is used to highlight and record other possible approaches to delivering the value proposed by a proposal.
|
|
|
|
## Additional Details
|
|
|
|
### Test Plan [optional]
|
|
|
|
**Note:** *Section not required until targeted at a release.*
|
|
|
|
Consider the following in developing a test plan for this proposal:
|
|
- 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.
|
|
|
|
## Implementation History
|
|
|
|
- [ ] MM/DD/YYYY: Proposed idea in an issue or community meeting
|
|
- [ ] MM/DD/YYYY: Compile a document following the proposal 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
|