From 9bd456c6df64adc221e4e089c9202139dfa3be90 Mon Sep 17 00:00:00 2001 From: Jeffrey Regan Date: Tue, 30 Apr 2019 09:05:17 -0700 Subject: [PATCH] Add bug report page. --- README.md | 65 +++++----------------------- docs/README.md | 24 +++++----- docs/bugs.md | 46 ++++++++++++++++++++ docs/{version2.0.0.md => v_2.0.0.md} | 6 +-- docs/{version2.1.0.md => v_2.1.0.md} | 8 ++-- 5 files changed, 76 insertions(+), 73 deletions(-) create mode 100644 docs/bugs.md rename docs/{version2.0.0.md => v_2.0.0.md} (99%) rename docs/{version2.1.0.md => v_2.1.0.md} (59%) diff --git a/README.md b/README.md index 631a5b580..7f010d89e 100644 --- a/README.md +++ b/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 -page], or see these [install] notes. Then try one of -the tested [examples]. +Download a binary from the [release page], or see +these [instructions](docs/INSTALL.md). + +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 - - -##### 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. +To file bugs please read [this](docs/bugs.md). 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 diff --git a/docs/README.md b/docs/README.md index d7786c882..b171fb4cb 100644 --- a/docs/README.md +++ b/docs/README.md @@ -1,18 +1,12 @@ # Documentation -## General - - * [Installation instructions](INSTALL.md) - - * [FAQ](FAQ.md) - - * [Glossary](glossary.md) - -## Examples + * [Installation](INSTALL.md) * [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 diff --git a/docs/bugs.md b/docs/bugs.md new file mode 100644 index 000000000..d3a0c311c --- /dev/null +++ b/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. diff --git a/docs/version2.0.0.md b/docs/v_2.0.0.md similarity index 99% rename from docs/version2.0.0.md rename to docs/v_2.0.0.md index 65d10f748..533b4f1ed 100644 --- a/docs/version2.0.0.md +++ b/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 diff --git a/docs/version2.1.0.md b/docs/v_2.1.0.md similarity index 59% rename from docs/version2.1.0.md rename to docs/v_2.1.0.md index 3b47ade73..2bf40dadd 100644 --- a/docs/version2.1.0.md +++ b/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`. - - * Order matters in `resources` (stretch goal). + * This is the last release with completely unsupported access to `pkg`.