Merge pull request #809 from christopherhein/chore/add-design-folder

✨📖 Adding designs folder and sample template

README.md

@@ -11,6 +11,7 @@ Documentation:
 - [Creating a manager](https://godoc.org/github.com/kubernetes-sigs/controller-runtime/pkg/manager#example-New)
 - [Creating a controller](https://godoc.org/github.com/kubernetes-sigs/controller-runtime/pkg/controller#example-New)
 - [Examples](https://github.com/kubernetes-sigs/controller-runtime/blob/master/examples)
+- [Designs](https://github.com/kubernetes-sigs/controller-runtime/blob/master/designs)
 
 # Versioning, Maintenance, and Compatibility
 

designs/README.md

@@ -0,0 +1,36 @@
+Designs
+=======
+
+These are design documents for changes to Controller Runtime They exist
+to help document the design processes that go into writing Controller 
+Runtime, but may not be up-to-date (more below).
+
+Not all changes to Controller Runtime 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 simultaneously 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
+
+**Controller Runtime documentation
+[GoDoc](https://godoc.org/sigs.k8s.io/controller-runtime) should be
+considered the canonical, update-to-date reference and architectural
+documentation** for Controller Runtime.
+
+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 opportunity 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 opportunity to stop and write a proof-of-concept, if
+you haven't already, which should help catch practical nits with the
+design. -->