Add bug writing instructions to README.

README.md

@@ -117,30 +117,87 @@ The YAML can be directly [applied] to a cluster:
 > kustomize build ~/someApp/overlays/production | kubectl apply -f -
 > ```
 
-## Community, discussion, contribution, and support
+## Community
 
-Learn how to engage with the Kubernetes community on the [community page].
+### Filing bug reports
 
-You can reach the maintainers of this project at:
+
+##### A good report specifies
+
+ * the output of `kustomize version`,
+ * the input (the content of `kustomization.yaml`
+   and any files it refers to),
+ * the expected YAML output.
+
+##### A _great_ report is a bug reproduction test
+ 
+Kustomize has a simple test harness in the
+[target package] for specifying a kustomization's
+input and the expected output.
+See this [example of a target test].
+ 
+The pattern is
+ * call `NewKustTestHarness`
+ * specify kustomization input data (resources,
+   patches, etc.) as inline strings,
+ * call `makeKustTarget().MakeCustomizedResMap()`
+ * compare the actual output to expected output
+
+In a bug reproduction test, the expected output string
+initially contains the _wrong_ (unexpected) output,
+thus unambiguously reproducing the bug.
+
+Nearby comments should explain what the output
+_should_ be, and have a TODO pointing to the related
+issue.
+
+The person who fixes the bug then has a clear
+bug reproduction and a test to modify when
+the bug is fixed.
+
+The bug reporter can then see the bug was fixed,
+and has permanent regression coverage to prevent
+its reintroduction.
+ 
+### Feature requests
+
+Feature requests are welcome.
+
+Before working on an implementation, please
+ * Read the [eschewed feature list].
+ * File an issue describing
+   how the new feature would behave
+   and label it [kind/feature].
+
+### Other communication channels
 
 - [Slack]
 - [Mailing List]
+- General kubernetes [community page]
 
 ### Code of conduct
 
-Participation in the Kubernetes community is governed by the [Kubernetes Code of Conduct].
+Participation in the Kubernetes community
+is governed by the [Kubernetes Code of Conduct].
 
-[DAM]: docs/glossary.md#declarative-application-management
-[KEP]: https://github.com/kubernetes/enhancements/blob/master/keps/sig-cli/0008-kustomize.md
 [`make`]: https://www.gnu.org/software/make
 [`sed`]: https://www.gnu.org/software/sed
+[DAM]: docs/glossary.md#declarative-application-management
+[KEP]: https://github.com/kubernetes/enhancements/blob/master/keps/sig-cli/0008-kustomize.md
+[Kubernetes Code of Conduct]: code-of-conduct.md
+[Mailing List]: https://groups.google.com/forum/#!forum/kubernetes-sig-cli
+[Slack]: https://kubernetes.slack.com/messages/sig-cli
 [applied]: docs/glossary.md#apply
 [base]: docs/glossary.md#base
+[community page]: http://kubernetes.io/community/
 [declarative configuration]: docs/glossary.md#declarative-application-management
+[eschewed feature list]: docs/eschewedFeatures.md
+[example of a target test]: https://github.com/kubernetes-sigs/kustomize/blob/master/pkg/target/baseandoverlaysmall_test.go
 [examples]: examples/README.md
 [imageBase]: docs/base.jpg
 [imageOverlay]: docs/overlay.jpg
 [install]: docs/INSTALL.md
+[kind/feature]: https://github.com/kubernetes-sigs/kustomize/labels/kind%2Ffeature
 [kubernetes style]: docs/glossary.md#kubernetes-style-object
 [kustomization]: docs/glossary.md#kustomization
 [overlay]: docs/glossary.md#overlay
@@ -149,10 +206,7 @@ Participation in the Kubernetes community is governed by the [Kubernetes Code of
 [resource]: docs/glossary.md#resource
 [resources]: docs/glossary.md#resource
 [sig-cli]: https://github.com/kubernetes/community/blob/master/sig-cli/README.md
+[target package]: https://github.com/kubernetes-sigs/kustomize/tree/master/pkg/target
 [variant]: docs/glossary.md#variant
 [variants]: docs/glossary.md#variant
 [workflows]: docs/workflows.md
-[community page]: http://kubernetes.io/community/
-[Kubernetes Code of Conduct]: code-of-conduct.md
-[Slack]: https://kubernetes.slack.com/messages/sig-cli
-[Mailing List]: https://groups.google.com/forum/#!forum/kubernetes-sig-cli

docs/eschewedFeatures.md

@@ -1,5 +1,10 @@
 # Eschewed Features
 
+The maintainers established this list to
+place bounds on the kustomize feature
+set.  The bounds can be changed with
+a consensus on the risks.
+
 For a bigger picture about why kustomize
 does some things and not others, see the
 glossary entry for [DAM].
@@ -10,8 +15,8 @@ glossary entry for [DAM].
 _compositions_ or _mixins_ - concepts that are widely accepted as
 a best practice in various programming languages.
 
-To this end, `kustomize` offers various _addition_ directives.  One
-can add labels, annotations, patches, resources and bases.
+To this end, `kustomize` offers various _addition_ directives.
+One may add labels, annotations, patches, resources, bases, etc.
 Corresponding _removal_ directives are not offered.
 
 Removal semantics would introduce many possibilities for