Merge pull request #5616 from leseb/design-guidelines

docs: add design doc template

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.
 

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).

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.