update readmes

INSTALL.md

@@ -0,0 +1,27 @@
+[release page]: https://github.com/kubernetes-sigs/kustomize/releases
+[Go]: https://golang.org
+
+## Installation
+
+Download a binary from the [release page].
+
+Or try this to grab the latest official release
+using the command line:
+
+```
+opsys=linux  # or darwin, or windows
+curl -s https://api.github.com/repos/kubernetes-sigs/kustomize/releases/latest |\
+  grep browser_download |\
+  grep $opsys |\
+  cut -d '"' -f 4 |\
+  xargs curl -O -L
+mv kustomize_*_${opsys}_amd64 kustomize
+chmod u+x kustomize
+```
+
+To install from head with [Go] v1.10.1 or higher:
+
+<!-- @installkustomize @test -->
+```
+go get github.com/kubernetes-sigs/kustomize
+```

README.md

@@ -1,5 +1,6 @@
-# kustomize
+[KEP]: https://github.com/kubernetes/community/blob/master/keps/sig-cli/0008-kustomize.md
-
+[`make`]: https://www.gnu.org/software/make
+[`sed`]: https://www.gnu.org/software/sed
 [applied]: docs/glossary.md#apply
 [base]: docs/glossary.md#base
 [declarative configuration]: docs/glossary.md#declarative-application-management
@@ -7,46 +8,51 @@
 [demos]: demos/README.md
 [imageBase]: docs/base.jpg
 [imageOverlay]: docs/overlay.jpg
+[installation]: INSTALL.md
 [kubernetes style]: docs/glossary.md#kubernetes-style-object
-[KEP]: https://github.com/kubernetes/community/blob/master/keps/sig-cli/0008-kustomize.md
 [kustomization]: docs/glossary.md#kustomization
 [overlay]: docs/glossary.md#overlay
+[overlays]: docs/glossary.md#overlay
+[release page]: https://github.com/kubernetes-sigs/kustomize/releases
+[resource]: docs/glossary.md#resource
 [resources]: docs/glossary.md#resource
 [sig-cli]: https://github.com/kubernetes/community/blob/master/sig-cli/README.md
+[variant]: docs/glossary.md#variant
+[variants]: docs/glossary.md#variant
 [workflows]: docs/workflows.md
 
+# kustomize
 
-`kustomize` is a command line tool supporting
+`kustomize` lets you customize raw, template-free YAML
-template-free customization of YAML (or JSON) objects
+files for multiple purposes, leaving the original YAML
-that conform to the [kubernetes style].  If your
+untouched and usable as is.
-objects have a `kind` and a `metadata` field,
-`kustomize` can patch them to support configuration
-sharing and re-use.
 
-For more details, try a [demo].
+`kustomize` targets kubernetes; it understands and can
+patch [kubernetes style] API objects.  It's like
+[`make`], in that what it does is declared in a file,
+and it's like [`sed`], in that it emits editted text.
 
 [![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 [installation] alternatives.
 
-## Installation
+Be sure to try one of the tested [demos].
-
-This assumes [Go](https://golang.org/) (v1.10.1 or higher)
-is installed and your `PATH` contains `$GOPATH/bin`:
-
-<!-- @installkustomize @test -->
-```
-go get github.com/kubernetes-sigs/kustomize
-```
-
 
 ## Usage
 
-#### 1) Make a customized base
 
-A [base] configuration is a [kustomization] file listing a set of
+### Make a [base]
-k8s [resources] - deployments, services, configmaps,
+
-secrets that serve some common purpose.
+In some directory containing your YAML [resource]
+files (deployments, services, configmaps, etc.), create a
+[kustomization] file.
+
+This file should declare those resources, and any
+common customization to apply to them, e.g. _add a
+common label_.
 
 ![base image][imageBase]
 
@@ -60,15 +66,30 @@ File structure:
 >     └── service.yaml
 > ```
 
-Your base could be a fork of someone else's
+This is your [base].  The resources in it could be a
-configuration, that your occasionally rebase from to
+fork of someone else's configuration.  If so, you can
-capture improvements.
+easily rebase from the source material to capture
+improvements, because you don't modify the resources
+directly.
 
-#### 2) Further customize with overlays
+Generate customized YAML with:
 
-An [overlay] customizes your base along different dimensions
+```
-for different purposes or different teams, e.g. for
+kustomize build ~/yourApp/base
-_development_ and _production_.
+```
+
+The YAML can be directly [applied] to a cluster:
+
+> ```
+> kustomize build ~/yourApp/base | kubectl apply -f -
+> ```
+
+
+###  Create [variants] of a common base using [overlays]
+
+Manage traditional [variants] of a configuration like
+_development_, _staging_ and _production_ using
+[overlays].
 
 ![overlay image][imageOverlay]
 
@@ -90,22 +111,23 @@ File structure:
 >         └── replica_count.yaml
 > ```
 
-Your overlays could sit in your own repository.
+Store your overlays in your own repository.  On disk,
+the overlay can reference a base in a sibling
+directory.  This avoids trouble with nesting git
+repositories.
 
-#### 3) Run kustomize
+Generate YAML with
-
-Run `kustomize` on an overlay, e.g.
 
 ```
 kustomize build ~/yourApp/overlays/production
 ```
 
-The result is printed to `stdout` as a set of complete
+The YAML can be directly [applied] to a cluster:
-resources, ready to be [applied] to a cluster.  See the
-[demos].
-
 
+> ```
+> kustomize build ~/yourApp/overlays/production | kubectl apply -f -
+> ```
 
 ## About
 
-This project is sponsored by [sig-cli] ([KEP]).
+This tool is sponsored by [sig-cli] ([KEP]).

build/README.md

@@ -1,28 +1,45 @@
-## Overview
+[releases page]: https://github.com/kubernetes-sigs/kustomize/releases
+[`container-builder-local`]: https://github.com/GoogleCloudPlatform/container-builder-local
+[Google Container Builder]: https://cloud.google.com/container-builder
 
-This directory contains scripts and configuration files for publishing a
+Scripts and configuration files for publishing a
-`kustomize` release on [release page](https://github.com/kubernetes-sigs/kustomize/releases)
+`kustomize` release on the [releases page].
 
-## Steps to run build a release locally
+### Build a release locally
-Install container-builder-local from [github](https://github.com/GoogleCloudPlatform/container-builder-local). 
 
-```sh
+Install [`container-builder-local`], then run
-container-builder-local --config=build/cloudbuild_local.yaml --dryrun=false --write-workspace=/tmp/w .
+
+```
+container-builder-local \
+   --config=build/cloudbuild_local.yaml \
+   --dryrun=false --write-workspace=/tmp/w .
 ```
 
-You will find the build artifacts under `/tmp/w/dist` directory
+to build artifacts under `/tmp/w/dist`.
 
-### Publishing a Release
+### Publish a Release
 
-Here are the steps to publish a new release.
+Get on an up-to-date master branch:
-
- - Figure out the next version (for ex. v1.0.3) to be released.
- - Ensure that you are on master branch and is up-to-date with the remote upstream/master branch. Do the following if you are in doubt:
 ```
 git checkout master
 git fetch upstream
 git rebase upstream/master
 ```
- - Tag the repo by running `git tag -a <version> -m "<version> release"`
+
- - Push the tag to `upstream` branch by running `git push upstream <version>`
+Decide on your version, e.g.:
- - Thats it! The new tag will trigger a job in Google Container Builder and new release should appear in the releases page.
+```
+version=v1.0.3
+```
+
+Tag the repo:
+```
+git tag -a $version -m "$version release"
+```
+
+Push the tag upstream:
+```
+git push upstream $version
+```
+
+The new tag will trigger a job in [Google Container
+Builder] to put a new release on the [releases page].

demos/README.md

@@ -1,7 +1,14 @@
 # Demos
 
 These demos assume that `kustomize` is on your `$PATH`.
-They are covered by pre-submit tests.
+
+They are covered by [pre-commit](../bin/pre-commit.sh)
+tests, and should work with HEAD
+
+<!-- @installkustomize @test -->
+```
+go get github.com/kubernetes-sigs/kustomize
+```
 
  * [hello world](helloWorld/README.md) - Deploy multiple
    (differently configured) variants of a simple Hello

docs/glossary.md

@@ -162,8 +162,8 @@ It's often abbreviated as _k8s_.
 
 An object, expressed in a YAML or JSON file, with the
 [fields required] by kubernetes.  Basically just a
-`kind` field to identify the type, a `metadata/name`
+_kind_ field to identify the type, a _metadata/name_
-field to identify the variant, and an `apiVersion`
+field to identify the variant, and an _apiVersion_
 field to identify the version (if there's more than one
 version).
 
@@ -267,7 +267,7 @@ configmap.
 
 More generally, a resource can be any correct YAML file
 that [defines an object](https://kubernetes.io/docs/concepts/overview/working-with-objects/kubernetes-objects/#required-fields)
-with a `kind` and a `metadata/name` field.
+with a _kind_ and a _metadata/name_ field.
 
 
 A _resource_ in the content of a REST-ful API is the
@@ -290,8 +290,7 @@ The _target_ is the argument to `kustomize build`, e.g.:
 > ```
 
 `$target` must be a path to a directory that
-immediately contains a file called
+immediately contains a [kustomization].
-`kustomization.yaml` (i.e. a [kustomization]).
 
 The target contains, or refers to, all the information
 needed to create customized resources to send to the
@@ -304,15 +303,15 @@ A target is a [base] or an [overlay].
 A _variant_ is the outcome, in a cluster, of applying
 an [overlay] to a [base].
 
-> E.g., a _staging_ and _production_ overlay both modify some
+E.g., a _staging_ and _production_ overlay both modify
-> common base to create distinct variants.
+some common base to create distinct variants.
->
+
-> The _staging_ variant is the set of resources
+The _staging_ variant is the set of resources exposed
-> exposed to quality assurance testing, or to some
+to quality assurance testing, or to some external users
-> external users who'd like to see what the next
+who'd like to see what the next version of production
-> version of production will look like.
+will look like.
->
+
-> The _production_ variant is the set of resources
+The _production_ variant is the set of resources
-> exposed to production traffic, and thus may employ
+exposed to production traffic, and thus may employ
-> deployments with a large number of replicas and higher
+deployments with a large number of replicas and higher
-> cpu and memory requests.
+cpu and memory requests.