Update README.md

pseudo/README.md

@@ -1,36 +1,57 @@
-# Pseudo Modules
+# Pseudo k8s
 
-This package contains dependencies copied from kubernetes/kubernetes repos which
-are synced out of staging.
+[kubernetes/api]: https://github.com/kubernetes/api
+[kubernetes/apimachinery]: https://github.com/kubernetes/apimachinery
+[kubernetes/client-go]: https://github.com/kubernetes/client-go
+[init-pseudo-module.sh]: init-pseudo-module.sh
 
-The long term plan is to move off of the staging libraries entirely in favor of
-more suitable libraries developed in the Kustomize repo.
+The module defined below in `pseudo/k8s` contains code generated by the
+[init-pseudo-module.sh] script.
+
+The module contains clones (see the [script][init-pseudo-module.sh] for the specific clone tag) of code from the following repositories:
+
+- [kubernetes/api]
+- [kubernetes/apimachinery]
+- [kubernetes/client-go]
+
+These repositories are in turn snapshots of code being developed
+in [kubernetes staging](https://github.com/kubernetes/kubernetes/tree/master/staging).
 
 ## Why?
 
-1. Vendoring the Kustomize API in other tools
+[`cli-runtime`]: https://github.com/kubernetes/kubernetes/tree/master/staging/src/k8s.io/cli-runtime
+[`apimachinery`]: https://github.com/kubernetes/kubernetes/tree/master/staging/src/k8s.io/apimachinery
 
-The Kubernetes staging packages do not have stable APIs, and frequently break compatibility.
-This makes it difficult for other tools to vendor the Kustomize APIs, as they may depend
-on incompatible versions of the staging APIs.  By forking the staging libraries, we
-ensure that we are using our own copy which will not conflict with other versions.
+In what follows, let the word `apimachinery` generally represent one of more of the modules [kubernetes/api], [kubernetes/apimachinery], [kubernetes/client-go].
 
-2. Vendoring into kubectl
+ - kubectl depends on `apimachinery` in the k/k repo via a `go.mod` replacement.
 
-Packages that depend upon staging may not be vendored into kubernetes/kubernetes.  By forking
-the staging packages, we break this circular dependency so that the kustomize packages may
-be vendored into kubernetes/kubernetes without depending on code originating out of
-kubernetes/kubernetes.
+ - kubectl must depend the on kustomize API module.
 
-## Who?
+ - `apimachinery` doesn’t yet do releases distinguished by major version number.  I.e., one cannot write a `go.mod` file containing the lines
+   > ```
+   > require k8s.io/apimachinery    v1.1.4
+   > require k8s.io/apimachinery/v2 v2.1.0
+   > require k8s.io/apimachinery/v3 v3.2.1
+   > ```
+   The only option at this time are pseudo-versions of the form `v0.0.0-20181127025237-2b1284ed4c93` and everything in the k/k repo must depend on exactly one pseudo version, which is typically a v.0.0.0 with a replace directive specifying an in-repo relative path.
 
-While it is possible to depend upon them from modules outside the Kustomize repository,
-there is not guarantee that this will continue to work in the future.
+ - kustomize depends on `apimachinery`.
 
-The pseudo modules may be removed at anytime in the future without warning and no
+This creates a problem, since kubectl and kustomize have no means to declare a dependence on different versions of `apimachinery`, and no means to sync on the same version since kubectl and kustomize live in different repositories.
+
+A solution to this is a _manual vendor_: either the kustomize API module source code must be manually snapshotted into the k/k repo at some invented path that could never be confused with a normal module import path, or the `apimachinery` module (and friends) must be snapshotted into the kustomize repo using the same notion of import path replacement.
+
+This module is the result of taking the latter option.  kustomize can depend on this snapshot of `apimachinery`, and both can be vendored into the k/k repo safely.
+
+
+## Caveats
+
+This pseudo k8s module may be removed at anytime in the future without warning and no
 support will be given for these modules.
+It's best to try to encourage semver development in `apimachinery` directly.
 
-## How?
+## How was this module made?
 
 These libraries were forked by running `git clone` to clone the repos.
 
@@ -41,6 +62,4 @@ These libraries were forked by running `git clone` to clone the repos.
 2. Run the [init-pseudo-module.sh](init-pseudo-module.sh) script to clone and configure pseudo deps
   - From the root directory -- `$ psuedo/init-pseudo-module.sh`
 
-### Using the Pseudo Modules in Kustomize
 
-TODO(pwittrock): Write this once it has been done successfully