Merge pull request #1031 from monopole/bugReportPage

Add bug report page.

README.md

@@ -16,14 +16,14 @@ inspired by [DAM].
 [![Build Status](https://travis-ci.org/kubernetes-sigs/kustomize.svg?branch=master)](https://travis-ci.org/kubernetes-sigs/kustomize)
 [![Go Report Card](https://goreportcard.com/badge/github.com/kubernetes-sigs/kustomize)](https://goreportcard.com/report/github.com/kubernetes-sigs/kustomize)
 
-**Installation**: Download a binary from the [release
+Download a binary from the [release page], or see
-page], or see these [install] notes. Then try one of
+these [instructions](docs/INSTALL.md).
-the tested [examples].
+
+Browse the [docs](docs) or jump right into the
+tested [examples](examples).
+
+kustomize [v2.0.3] is available in [kubectl v1.14][kubectl].
 
-**Note** Kustomize is now available on kubectl v1.14 and can be used by specifying a directory containing a `kustomization.yaml`:
-```shell
-kubectl apply -k dir/
-```
 
 ## Usage
 
@@ -124,51 +124,10 @@ The YAML can be directly [applied] to a cluster:
 
 ## Community
 
-### Filing bug reports
+To file bugs please read [this](docs/bugs.md).
-
-
-##### 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
@@ -197,12 +156,10 @@ is governed by the [Kubernetes Code of Conduct].
 [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
+[kubectl]: https://kubernetes.io/blog/2019/03/25/kubernetes-1-14-release-announcement
 [kubernetes style]: docs/glossary.md#kubernetes-style-object
 [kustomization]: docs/glossary.md#kustomization
 [overlay]: docs/glossary.md#overlay
@@ -211,7 +168,7 @@ is governed by the [Kubernetes Code of Conduct].
 [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
+[v2.0.3]: https://github.com/kubernetes-sigs/kustomize/releases/tag/v2.0.3
 [workflows]: docs/workflows.md

docs/README.md

@@ -1,18 +1,12 @@
 # Documentation
 
-##  General
+ * [Installation](INSTALL.md)
-
- * [Installation instructions](INSTALL.md)
-
- * [FAQ](FAQ.md)
-
- * [Glossary](glossary.md)
-
-##  Examples
 
  * [Examples](../examples) - detailed walkthroughs of various
     workflows and concepts.
 
+ * [Glossary](glossary.md) - the word of the day is [_root_](glossary.md#kustomization-root).
+
  * [kustomization.yaml](kustomization.yaml) - a
    [kustomization](glossary.md#kustomization) file
    with explanations of each field.
@@ -23,11 +17,16 @@
  * [Workflows](workflows.md) - steps one might take in
    using bespoke and off-the-shelf configurations.
 
+ * [FAQ](FAQ.md)
+
+
 ## Release notes
 
- * [2.1](version2.1.0.md)
+ * [2.1](v_2.1.0.md)
+
+ * [2.0](v_2.0.0.md) -
+   kustomize [v2.0.3] is available in [kubectl v1.14][kubectl].
 
- * [2.0](version2.0.0.md)
 
 ## Policies
 
@@ -41,3 +40,6 @@
    before sending a PR.
 
  * [Code of conduct](../code-of-conduct.md)
+
+[v2.0.3]: https://github.com/kubernetes-sigs/kustomize/releases/tag/v2.0.3
+[kubectl]: https://kubernetes.io/blog/2019/03/25/kubernetes-1-14-release-announcement

docs/bugs.md

@@ -0,0 +1,46 @@
+# Filing bugs
+
+[target package]: https://github.com/kubernetes-sigs/kustomize/tree/master/pkg/target
+[example of a target test]: https://github.com/kubernetes-sigs/kustomize/blob/master/pkg/target/baseandoverlaysmall_test.go
+
+File issues as desired, but
+if you've found a problem with how
+`kustomize build` works, consider the
+following to improve response time.
+
+## 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.

docs/v_2.0.0.md

@@ -1,4 +1,4 @@
-# Kustomize 2.0.0
+# kustomize 2.0.0
 
 After security review, a field used in secret generation (see below) was removed from the definition of a kustomization file with no mechanism to convert it to a new form. Also, the set of files accessible from a kustomization file has been further constrained.
 
@@ -47,9 +47,9 @@ there are no major new features to announce. A few things that are worth mention
     - name: postgres
       newTag: v1
   ```
-  
+
   will be converted to
-  
+
   ```
   apiVersion: kustomize.config.k8s.io/v1beta1
   kind: Kustomization

docs/v_2.1.0.md

@@ -1,6 +1,6 @@
-# Verision 2.1.0
+# kustomize 2.1.0
 
-TODO: provide details
+_TODO: provide details_
 
  * The `inventory` field.
 
@@ -13,6 +13,4 @@ TODO: provide details
 
  * GO modules
 
- * The last release with completely unsupported access to `pkg`.
+ * This is the last release with completely unsupported access to `pkg`.
-
- * Order matters in `resources` (stretch goal).