design document template (#2563)

* updated maintainers

* update to the front page

* installation paragraph

* design doc template

* additional process detail

* slight updates

Author: mikebz

CONTRIBUTING.md

@@ -15,6 +15,19 @@ You generally only need to submit a CLA once, so if you've already submitted one
 (even if it was for a different project), you probably don't need to do it
 again.
 
+## Contributing large features
+
+Larger features and all the features that affect the interface (CLI or API) of
+kpt need to have a reviewed and merged design document.  It is OK to start with
+a prototype in your private fork but if you intend for your feature to be
+shipped in kpt please create a design document with this 
+[design template](/docs/design-docs/00-template.md).
+
+You should create a copy of the template and submit a PR for comments and 
+review by maintainers.  Once the PR is merged the design is considered approved.
+The actual code change PRs should link to the design documents, even though it
+is well understood that the design can drift during implementation.
+
 ## Code reviews
 
 All submissions, including submissions by project members, require review. We

MAINTAINERS

@@ -1,3 +1,5 @@
 Mortent Torkildsen <[email protected]>
-Jeffrey Regan <jregan@google.com>
+Sunil Arora <sunilarora@google.com>
 Frank Farzan <[email protected]>
+Phani Teja Marupaka <[email protected]>
+Mengqi Yu <[email protected]>

README.md

@@ -1,4 +1,42 @@
 # kpt
 
-- [Documentation for version >= v1.0](https://kpt.dev/)
-- [Documentation for version <= v0.39](https://googlecontainertools.github.io/kpt/)
+kpt is a git-native, schema-aware, extensible client-side tool for packaging, 
+customizing, validating, and applying Kubernetes resources.
+
+## Why kpt?
+
+1. kpt allows you to share, use and update packages of Kubernetes resources
+using any git repo.  No special setup is necessary.
+2. kpt allows customization of packages using an editor of your choice. The 
+resource merge feature of kpt will handle a lot of the scenarios of merging 
+upstream changes on update.
+3. Customization in kpt is done without templates, domain specific languages
+and paramters. Any engineer who is familiar with Kubernetes to work on the 
+infrastructure configuration.
+4. kpt apply addresses some of the functional gaps in `kubectl apply` such as
+pruning and reconciling status.
+
+The best place to get started and learn about specific features of kpt is 
+to visit the [kpt website](https://kpt.dev/).
+
+### Install kpt
+
+kpt installation instructions can be found on 
+[kpt.dev/installation](https://kpt.dev/installation/)
+
+## Roadmap
+
+You can read about the big upcoming features in the 
+[roadmap doc](/docs/ROADMAP.md).
+
+## Contributing
+
+If you are interested in contributing please start with 
+[contribution guidelines](CONTRIBUTING.md).
+
+## Contact
+
+We would love to keep in touch:
+
+1. Join our [Slack channel](https://kubernetes.slack.com/channels/kpt)
+1. Join our [email list](https://groups.google.com/forum/?oldui=1#!forum/kpt-users)

docs/design-docs/00-template.md

@@ -0,0 +1,73 @@
+# Title
+
+* Author(s): \<your name\>, \<your github alias\>
+* Approver: \<kpt-maintainer\>
+
+>    Every feature will need design sign off an PR approval from a core
+>    maintainer.  If you have not got in touch with anyone yet, you can leave
+>    this blank and we will try to line someone up for you.
+
+## Why
+
+Please provide a reason to have this feature.  For best results a feature should
+be addressing a problem that is described in a github issue.  Link the issues
+in this section.  The more user requests are linked here the more likely this
+design is going to get prioritized on the roadmap.
+
+It's good to include some background about the problem, but do not use that as a
+substitute for real user feedback.
+
+## Design
+
+Please describe your solution. Please list any:
+
+* new config changes
+* interface changes
+* design assumptions
+
+For a new config change, please mention:
+
+* Is it backwards compatible? If not, what is the migration and deprecation 
+  plan?
+
+
+## User Guide
+
+This section should be written in the form of a detailed user guide describing 
+the user journey. It should start from a reasonable initial state, often from 
+scratch (Instead of starting midway through a convoluted scenario) in order 
+to provide enough context for the reader and demonstrate possible workflows. 
+This is a form of DDD (Documentation-Driven-Development), which is an effective 
+technique to empathize with the user early in the process (As opposed to 
+late-stage user-empathy sessions).
+
+This section should be as detailed as possible. For example if proposing a CLI 
+change, provide the exact commands the user needs to run, along with flag 
+descriptions, and success and failure messages (Failure messages are an 
+important part of a good UX). This level of detail serves two functions:
+
+It forces the author and the readers to explicitly think about possible friction
+points, pitfalls, failure scenarios, and corner cases (“A measure of a good 
+engineer is not how clever they are, but whether they think about all the 
+corner cases”). Makes it easier to author the user-facing docs as part of the 
+development process (Ideally as part of the same PR) as opposed to it being an 
+afterthought.
+
+## Open Issues/Questions
+
+Please list any open questions here in the following format:
+
+### \<Question\>
+
+Resolution: Please list the resolution if resolved during the design process or
+specify __Not Yet Resolved__
+
+## Alternatives Considered
+
+If there is an industry precedent or alternative approaches please list them 
+here as well as citing *why* you decided not to pursue those paths.
+
+### \<Approach\>
+
+Links and description of the approach, the pros and cons identified during the 
+design.