Merge pull request #613 from DirectXMan12/docs/design-template

🏃 add a design folder and template

README.md

@@ -31,6 +31,7 @@ Check out the Kubebuilder [book](http://book.kubebuilder.io).
 - Slack channel: [#kubebuilder](http://slack.k8s.io/#kubebuilder)
 - Google Group: [kubebuilder@googlegroups.com](https://groups.google.com/forum/#!forum/kubebuilder)
 - Planned Work: [Sprint Dashboard](https://github.com/kubernetes-sigs/kubebuilder/projects/1)
+- Design Documents: [design](design/).
 
 ## Motivation
 

designs/README.md

@@ -0,0 +1,37 @@
+Designs
+=======
+
+These are design documents for changes to KubeBuilder (and
+cross-repository changes for related projects, like controller-runtime and
+controller-tools). They exist to help document the design processes that
+go into writing KubeBuilder, but may not be up-to-date (more below).
+
+Not all changes to KubeBuilder need a design document -- only major ones.
+Use your best judgement.
+
+When submitting a design document, we encourage having written
+a proof-of-concept, and it's perfectly acceptable to submit the
+proof-of-concept PR simulatenously with the design document, as the
+proof-of-concept process can help iron out wrinkles and can help with the
+`Example` section of the template.
+
+## Out-of-Date Designs
+
+**KubeBuilder documentation (the [book](https://book.kubebuilder.io) and
+the [GoDoc](https://godoc.org/sigs.k8s.io/controller-runtime)) should be
+considered the canonical, update-to-date reference and architectural
+documentation** for KubeBuilder.
+
+However, if you see an out-of-date design document, feel free to submit
+a PR marking it as such, and add an addendum linking to issues documenting
+why things changed.  For example:
+
+```markdown
+
+# Out of Date
+
+This change is out of date.  It turns out curly braces a frustrating to
+type, so we had to abandon functions entirely, and have users specify
+custom functionality using strings of Common LISP instead.  See #000 for
+more information.
+```

designs/template.md

@@ -0,0 +1,21 @@
+Title of the Design
+===================
+
+<!-- Describe your change here.  This is purposefully freeform: we want
+enough information to evaluate the design, but not so much that you're
+annoyed by the overall design process and decide to bake cookies instead.
+-->
+
+## Example
+
+<!-- Specify an example of how the user would use this.  It helps other
+contributors get a feel for how this will look in real code, and provides
+a good oportunity to evaluate the end-user feel of the code for yourself.
+
+If you find yourself groaning at verbosity, copy-and-pasting a lot, or
+writing a bunch of tiny helper functions, it's a good indication that you
+might need to re-evaluate the user experience of your design.
+
+This is also a good oportunity to stop and write a proof-of-concept, if
+you haven't already, which should help catch practical nits with the
+design. -->