From 3ab437e757c2ff5575f39eafa8f71aee7d3a70ec Mon Sep 17 00:00:00 2001
From: Solly Ross <sollyross@google.com>
Date: Wed, 27 Feb 2019 17:03:13 -0800
Subject: [PATCH] :running: add a design folder and template

This adds a design folder and template that we can use for documenting
major design decisions.
---
 README.md           |  1 +
 designs/README.md   | 37 +++++++++++++++++++++++++++++++++++++
 designs/template.md | 21 +++++++++++++++++++++
 3 files changed, 59 insertions(+)
 create mode 100644 designs/README.md
 create mode 100644 designs/template.md

diff --git a/README.md b/README.md
index 6f2ceb2436..f3e476e638 100644
--- a/README.md
+++ b/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
 
diff --git a/designs/README.md b/designs/README.md
new file mode 100644
index 0000000000..793b4d04f8
--- /dev/null
+++ b/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.
+```
diff --git a/designs/template.md b/designs/template.md
new file mode 100644
index 0000000000..2f50c75196
--- /dev/null
+++ b/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. -->