From f17698a8ea877e09a4bbaaad99295dec5291c83d Mon Sep 17 00:00:00 2001
From: Jeffrey Regan <jregan@google.com>
Date: Tue, 18 Jun 2019 13:33:20 -0700
Subject: [PATCH] More release note tweaks.

---
 docs/v_2.1.0.md | 129 +++++++++++++++++++++++++-----------------------
 1 file changed, 67 insertions(+), 62 deletions(-)

diff --git a/docs/v_2.1.0.md b/docs/v_2.1.0.md
index 7174db868..d7a35d938 100644
--- a/docs/v_2.1.0.md
+++ b/docs/v_2.1.0.md
@@ -150,78 +150,83 @@ For more information see the
 
 ## Field changes / deprecations
 
-* Generalized `resources` field.
+###  `resources` expanded, `bases` deprecated
 
-  The `resources` field has been generalized; it
-  now accepts what formerly could only be
-  specified in the `bases` field.
+The `resources` field has been generalized; it now
+accepts 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.
+This change was made to allow users fine control
+over resource processing order.  With a distinct
+`bases` field, bases had to be loaded separately
+from resources as a group.  Now, base loading may
+be interleaved as desired with the loading of
+resource files from the current
+directory. [Resource ordering](#resource-ordering)
+had to be respected before this feature could be
+introduced.
 
-  > 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 is now deprecated, and will be
+deleted in some future major release.  Manage the
+deprecation simply moving the arguments of the
+`bases` field to the `resources` field in the
+desired order, e.g.
 
-  The `bases` field still works, but is
-  deprecated.  Deal with this by simply moving the
-  arguments of the `bases` field to the
-  `resources` field in the desired order, e.g.
+> ```
+> resources:
+> - someResouceFile.yaml
+> - someOtherResourceFile.yaml
+> bases:
+> - ../../someBaseDir
+> ```
 
-  > ```
-  > resources:
-  > - someResouceFile.yaml
-  > - someOtherResourceFile.yaml
-  > bases:
-  > - ../../someBaseDir
-  > ```
+could become
 
-  could become
+> ```
+> resources:
+> - someResouceFile.yaml
+> - ../../someBaseDir
+> - someOtherResourceFile.yaml
+> ```
 
-  > ```
-  > resources:
-  > - someResouceFile.yaml
-  > - ../../someBaseDir
-  > - someOtherResourceFile.yaml
-  > ```
-  
-  The depth-first traversal order of items in the
-  `resources:` field is respected by
-  kustomize, allowing one to, say, process
-  `someBaseDir` between the two resource files.
-  See this discussion of
-  [the `build --reorder` flag](#resource-ordering).
- 
-  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 `kustomized edit fix` command will do this for
+you, though it will always put the bases at the
+end.
 
-  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]).
+As an aside, the `resources`, `generators` and
+`transformers` fields now all accept the same
+argument format.
+
+> 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 path or URL
+> pointing to a directory with a kustomization
+> file).  A kustomization directory used in this
+> context is called a [_base_].
+
+The fact that the `generators` and `transformers`
+field accept [bases] and the fact that generator
+and transformer configuration objects are just
+normal k8s resources means that one can generate
+or transform a generator or a transformer (see
+[TestTransformerTransformers]).
 
 [TestTransformerTransformers]: ../pkg/target/transformerplugin_test.go
 
-* Consistent `envs` field for Secret and
-  ConfigMap generators.
+### `replicas` field
 
-  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`.
+The common task of patching a deployment to edit
+the number of replicas is now made easier
+with the new [replicas](fields.md#replicas) field. 
 
-Optionally `kustomize edit fix` to edit your
-kustomization file (e.g. merge singular `env`
-field into a plural field).
+### `envs` field
+
+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`.
+
+Optionally use `kustomize edit fix` to merge
+singular `env` field into a plural field.