Update README to explain versioning better

CHANGELOG.md

@@ -1,5 +1,18 @@
+
+TODO: This document was neglected and is currently not complete. Working on
+fixing this.
+
+# HEAD (changes that will go into the next release)
+
+# v2.0.0-alpha.1 (2.0.0 not released yet)
+
+* Removed top-level version folder (e.g., 1.4 and 1.5), switching to maintaining separate versions
+  in separate branches.
+
 # v1.5.0
 
+* TODO
+
 ## Changelog since v1.4.0
 
 ### Added

README.md

@@ -26,34 +26,87 @@ Go clients for talking to a [kubernetes](http://kubernetes.io/) cluster.
 
 ### Versioning
 
-`client-go` version numbers are unrelated to Kubernetes version numbers. Please see the [compatibility matrix](#compatibility-matrix) for the compatible Kubernetes clusters.
+`client-go` follows [semver](http://semver.org/). We will not make
+backwards-incompatible changes without incrementing the major version number. A
+change is backwards-incompatible either if it *i)* changes the public interfaces
+of `client-go`, or *ii)* makes `client-go` incompatible with otherwise supported
+versions of Kubernetes clusters.
 
-`client-go` follows [semver](http://semver.org/). We will not make backwards-incompatible changes without incrementing the major version number. A change is backwards-incompatible either if it *i)* changes the public interfaces of `client-go`, or *ii)* makes `client-go` incompatible with otherwise supported versions of Kubernetes clusters.
+Changes that add features in a backwards-compatible way will result in bumping
+the minor version (second digit) number.
 
-We will create a new branch for each increment in the major version number or minor version number. We will create a new tag for each increment in the patch version number. See [semver](http://semver.org/) for definitions of major, minor, and patch.
+Bugfixes will result in the patch version (third digit) changing. PRs that are
+cherry-picked into an older Kubernetes release branch will result in an update
+to the corresponding branch in `client-go`, with a corresponding new tag
+changing the patch version.
 
-The master branch will track the head in the main Kubernetes repo and accumulating changes. We will make a new client-go major/minor/patch version when:
+A consequence of this is that `client-go` version numbers will be unrelated to
-* A new major (very rare) or a new minor version is released in the Kubernetes main repository.
+Kubernetes version numbers.
-* A feature or a bug fix in the master branch is popular and users want it in a stable branch or with a stable tag. 
+
+#### Branches and tags.
+
+We will create a new branch and tag for each increment in the major version number or
+minor version number. We will create only a new tag for each increment in the patch
+version number. See [semver](http://semver.org/) for definitions of major,
+minor, and patch.
+
+The master branch will track HEAD in the main Kubernetes repo and
+accumulate changes. Consider HEAD to have the version `x.(y+1).0-alpha` or
+`(x+1).0.0-alpha` (depending on whether it has accumulated a breaking change or
+not), where `x` and `y` are the current major and minor versions.
 
 #### Compatibility: your code <-> client-go
 
-`client-go` follows [semver](http://semver.org/), so until the major version of client-go gets increased, your code will compile and will continue to work with explicitly supported versions of Kubernetes clusters.
+`client-go` follows [semver](http://semver.org/), so until the major version of
+client-go gets increased, your code will compile and will continue to work with
+explicitly supported versions of Kubernetes clusters. You must use a dependency
+management system and pin a specific major version of `client-go` to get this
+benefit, as HEAD follows the upstream Kubernetes repo.
 
 #### Compatibility: client-go <-> Kubernetes clusters
 
-`client-go` versions will be backwards compatible with many Kubernetes clusters. As we increment `client-go` versions, we will note which Kubernetes versions we expect them to work with. 
+Since Kubernetes is backwards compatible with clients, older `client-go`
+versions will work with many different Kubernetes cluster versions.
+
+We will backport bugfixes--but not new features--into older versions of
+`client-go`.
 
-We do not back-port new Kubernetes features into older clients. If you need a new feature, you are expected to upgrade to the new client. You can check out the [CHANGELOG](./CHANGELOG.md) for notable changes.
 
 #### Compatibility matrix
 
-* **client-go/1.4** is compatible with Kubernetes 1.3 through 1.5; it includes all features provided by Kubernetes 1.4.
+|                | Kubernetes 1.3 | Kubernetes 1.4 | Kubernetes 1.5 | Kubernetes 1.6 (not released yet) |
-* **client-go/1.5** is compatible with Kubernetes 1.3 through 1.5; it includes all features provided by Kubernetes 1.4.
+|----------------|----------------|----------------|----------------|----------------|
+| client-go 1.4  | +              | ✓              | -              | -              |
+| client-go 1.5  | +              | +              | ✓              | -              |
+| client-go 2.0  | +              | +              | ✓              | -              |
+| client-go HEAD | +              | +              | +              | ✓              |
+
+Key:
+
+* ✓ Exactly the same features / API objects in both client-go and the Kubernetes
+  version.
+* + client-go has features or api objects that may not be present in the
+  Kubernetes cluster, but everything they have in common will work.
+* - The Kubernetes cluster has features the client-go library can't use
+  (additional API objects, etc).
+
+See the [CHANGELOG](./CHANGELOG.md) for a detailed description of changes
+between client-go versions.
+
+|                | Canonical source code location                                       |
+|----------------|----------------------------------------------------------------------|
+| client-go 1.4  | Kubernetes main repo, 1.4 branch                                     |
+| client-go 1.5  | Kubernetes main repo, 1.5 branch                                     |
+| client-go 2.0  | Kubernetes main repo, 1.5 branch                                     |
+| client-go HEAD | Kubernetes main repo, master branch                                  |
+
 
 #### Why do the 1.4 and 1.5 branch contain top-level folder named after the version?
 
-1.4 and 1.5 branch keep the top-level folders so they do not break the import lines of existing users. These top-level folders are deprecated and are removed from the master branch and future branches.
+For the initial release of client-go, we thought it would be easiest to keep
+separate directories for each minor version. That soon proved to be a mistake.
+We are keeping the top-level folders in the 1.4 and 1.5 branches so that
+existing users won't be broken.
 
 ### How to get it