From db17533435223958100084a5d1bf2294f0ba78a9 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?S=C3=A9bastien=20Han?= Date: Mon, 8 Jun 2020 12:35:20 +0200 Subject: [PATCH] docs: add design doc template MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Rook already has a design process in place when introducing new functionality. The only missing thing is a clear template to bring consistency in our design documents. This is inspired and shrunk version of https://github.com/openshift/enhancements/tree/master/guidelines to add some guidelines when it comes to writing a design document. Signed-off-by: Sébastien Han --- Documentation/development-flow.md | 7 +++++ design/README.md | 3 +++ design/design_template.md | 43 +++++++++++++++++++++++++++++++ 3 files changed, 53 insertions(+) create mode 100644 design/README.md create mode 100644 design/design_template.md diff --git a/Documentation/development-flow.md b/Documentation/development-flow.md index 352a23150..030cee45a 100644 --- a/Documentation/development-flow.md +++ b/Documentation/development-flow.md @@ -157,6 +157,12 @@ To add a feature or to make a bug fix, you will need to create a branch in your ### Design Document For new features of significant scope and complexity, a design document is recommended before work begins on the implementation. +So create a design document if: + +* Adding a new storage provider +* Adding a new CRD +* Adding a significant feature to an existing storage provider. If the design is simple enough to describe in a github issue, you likely don't need a full design doc. + For smaller, straightforward features and bug fixes, there is no need for a design document. Authoring a design document for big features has many advantages: @@ -167,6 +173,7 @@ Authoring a design document for big features has many advantages: Note that writing code to prototype the feature while working on the design may be very useful to help flesh out the approach. A design document should be written as a markdown file in the [design folder](/design). +You can follow the process outlined in the [design template](/design/design_template.md). You will see many examples of previous design documents in that folder. Submit a pull request for the design to be discussed and approved by the community before being merged into master, just like any other change to the repository. diff --git a/design/README.md b/design/README.md new file mode 100644 index 000000000..f443ff8c2 --- /dev/null +++ b/design/README.md @@ -0,0 +1,3 @@ +# Rook Feature Proposal + +Please follow the [design section guideline](https://rook.io/docs/rook/master/development-flow.html#design-document). diff --git a/design/design_template.md b/design/design_template.md new file mode 100644 index 000000000..0f58a3ff7 --- /dev/null +++ b/design/design_template.md @@ -0,0 +1,43 @@ +--- +title: feature-name +target-version: release-X.X +--- + +# Feature Name + +## Summary + +### Goals + +List the specific goals of the proposal. How will we know that this has succeeded? + +### Non-Goals + +What is out of scope for this proposal? Listing non-goals helps to focus discussion +and make progress. + +## Proposal details + +This is where we get down to the nitty gritty of what the proposal actually is. +API changed in any, Golang snippets. + +### Risks and Mitigation + +What are the risks of this proposal and how do we mitigate. Think broadly. For +example, consider both security and how this will impact the larger OKD +ecosystem. + +## Drawbacks + +The idea is to find the best form of an argument why this feature should _not_ be implemented. + +## Alternatives + +Similar to the `Drawbacks` section the `Alternatives` section is used to +highlight and record other possible approaches to delivering the value proposed +by a feature. + +## Open Questions [optional] + +This is where to call out areas of the design that require closure before deciding +to implement the design.