Update 2.1 release notes before release.

docs/v_2.1.0.md

@@ -1,62 +1,179 @@
 # kustomize 2.1.0
 
-Lots of bug fixes since 2.0.3, and too many commits (over 300).
 
-Summary:  Go modules, inventory, plugins, eased loading restrictions.
+[Go modules]: https://github.com/golang/go/wiki/Modules
+[generator options]: ../examples/generatorOptions.md
+[imgModules]: images/goModules.png
+[imgPlugins]: images/plugins.png
+[imgPruning]: images/pruning.png
+[imgWheels]: images/abandonedTrainingWheels.png
+[kustomization]: glossary.md#kustomization
+[_kustomization_]: glossary.md#kustomization
+[base]: glossary.md#base
+[bases]: glossary.md#base
+[_base_]: glossary.md#base
+[kustomize inventory object documentation]: inventory_object.md
+[kustomize plugin documentation]: plugins.md
+[root]: glossary.md#kustomization-root
+[transformer configs]: ../examples/transformerconfigs
+[v1.0.9]: https://github.com/kubernetes-sigs/kustomize/releases/tag/v1.0.9
+[v2.0.3]: https://github.com/kubernetes-sigs/kustomize/releases/tag/v2.0.3
+[v2.1.0]: https://github.com/kubernetes-sigs/kustomize/releases/tag/v2.1.0
+[versioning policy]: versioningPolicy.md
+
+_Summary_: Go modules, inventory, plugins, eased
+loading restrictions, and about ~80 issues closed
+since [v2.0.3] (over 300 commits).
+
 
 
 ## Go modules
 
-Kustomize now defines it dependencies in a `go.mod` file, 
-and how this is used to support kustomize libraries
-for use in other tools will start evolving.
+![gopher with boxes][imgModules]
 
-## The inventory
+Kustomize now defines its dependencies in a top
+level `go.mod` file.  This is the first step
+towards a package structure intentially exported
+as one or more [Go modules] for use in other
+programs (kubectl, kubebuilder, etc.) and in
+kustomize plugins (see below).
 
-This is an alpha feature.
+
+## Inventory generation for pruning
+
+![pruning dead branches][imgPruning]
 
 Users can add an `inventory` stanza to their
-kustomization file, to add a special inventory
-object to the build result.  This object can be
-applied to the cluster and used to manage
-intelligent history aware pruning.
+kustomization file, to add a special _inventory
+object_ to the `build` result.
+
+This object applies to the cluster along with
+everything else in the build result and can be
+used by other clients to intelligently _prune_
+orphaned cluster resources.
+
+For more information see the
+[kustomize inventory object documentation].
 
-Details [here](inventory_object.md).
 
 ## Generator and transformer plugins
 
-Kustomize reads or creates resources, transforms
-them, and emits them as YAML.  The kustomization
-file is a declaration of how this works.
+![kid putting knife in electrical outlet][imgPlugins]
+
+Since the beginning (as `kinflate` back in Sep
+2017), kustomize has read or generated resources,
+applied a series of pipelined transformation to
+them, and emitted the result to `stdout`.
+
+At that time, the only way to change the behavior
+of a generator (e.g. a secret generator), or
+change the behavior of a transformer (e.g. a name
+changer, or json patcher), was to modify source
+code and put out a release.
+
+[v1.0.9] introduced [generator options] as a means
+to change the behavior of the only two generators
+available at the time - Secret and ConfigMap
+generators.  It also introduced
+[transformer configs] as a way to fine tune the
+targets of transformations (e.g. to which fields
+_selectors_ should be added).  Most of the feature
+requests for kustomize revolve around changing the
+behavior of the builtin generators and
+transformers.
+
+[v2.1.0] adds a _alpha_ plugin framework, that
+encourages users to write their own generators or
+transformers, _declaring them as kubernetes
+objects just like everything else_, and apply them
+as part of the `kustomize build` process.
+
+To inform the API exposed to plugins, and to
+confirm that the plugin framework can offer plugin
+authors the same capabilities as builtin
+operations, all the builtin generators and
+tranformers have been converted to plugin form
+(with a few exceptions awaiting Go module
+refinements).  This means that adding, say, a
+`secretGenerator` or `commonAnnotations` directive
+to your kustomization will (in [v2.1.0]) trigger
+execution of
+[code committed as a plugin](../plugin/builtin).
+
+For more information, see the
+[kustomize plugin documentation].
+
+## Remove load restrictions
+
+![removed training wheels][imgWheels]
+
+The following usage:
+
+```
+kustomize build --load_restrictions none $target
+```
+
+allows a `kustomization.yaml` file used in this
+build to refer to files outside its own directory
+(i.e. outside its [root]).
+
+This is an opt-in to suppress a security feature
+that denies this precise behavior.
+
+This feature should only be used to allow multiple
+overlays (e.g. prod, staging and dev) to share a
+patch file.  To share _resources_, use a relative
+path or URL to a kustomization directory in the
+`resources` directive.
 
 
+## Field changes / deprecations
 
+* Generalized `resources` field.
 
+  The `resources` field has been generalized, and
+  can now accept what formerly could only
+  be specified in the `bases` field.
 
+  This change was made so that the `resources`,
+  `generators` and `transformers` fields all
+  accept the same argument format.
 
-The client can recognize this object by name and use it to do a better job
-with actions like `apply`, `prune` and `delete`.
+  Each field's argument is a _string list_, where
+  each entry is either a _resource_ (a relative
+  path to a YAML file) or a [_kustomization_] (a
+  relative path or URL pointing to a directory
+  with a kustomization file).  A kustomization
+  directory used in this context is called a
+  [_base_].
 
+  The `bases` field still works, but is no longer
+  necessary, and will likely be deprecated in the
+  next release.  The _base_ as a concept is as
+  important as ever, it's just that two new fields
+  (`generators` and `tranformers`) and one existing
+  field (`resources`) now accept arguments
+  that were once accepted only by `bases`.
 
+  The fact that the `generators` and
+  `transformers` field accept [bases]
+  (i.e. kustomization directories) and the fact
+  that generator and transformer configuration
+  objects are normal k8s resources means that one
+  can generate or transform a generator or a
+  transformer (see [TestTransformerTransformers]).
 
+[TestTransformerTransformers]: ../pkg/target/transformerplugin_test.go
 
- * The `generators` and `transformers` fields.
-   See [plugins](plugins.md).
+* Consistent `envs` field for Secret and
+  ConfigMap generators.
 
- * The `--load_restrictions none` flag.
+  An `envs` sub-field has been added to both
+  `configMapGenerator` and `secretGenerator`,
+  replacing the now deprecated (and singular)
+  `env` field.  The new field accepts lists, just
+  like its sibling fields `files` and `literals`.
 
- * Field changes / deprecations (use `kustomize fix`)
-
-   * The `resources` field generalized, can accept
-     what was being placed in bases.
-     
-     `bases` field deprecated.
-
-   * New `envs` sub-field introduced to both
-     `configMapGenerators` and `secretGenerators`,
-     replacing the deprecated `env` field
-     (allowing mixins of k=v pairs from different files).
-
- * GO modules
-
- * Last release with completely unsupported access to `pkg`.
+Optionally `kustomize edit fix` to edit your
+kustomization file (e.g. merge singular `env`
+field into a plural field).