From a0a777840a5645f8ad29ff66a999f73ddf975fe3 Mon Sep 17 00:00:00 2001 From: Daniel Smith Date: Tue, 14 Feb 2017 16:15:21 -0800 Subject: [PATCH] Update README to explain versioning better --- CHANGELOG.md | 13 +++++++++ README.md | 77 ++++++++++++++++++++++++++++++++++++++++++++-------- 2 files changed, 78 insertions(+), 12 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 97cf022c..c48047d0 100644 --- a/CHANGELOG.md +++ b/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 diff --git a/README.md b/README.md index a2bce817..15d2a73b 100644 --- a/README.md +++ b/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 new major (very rare) or a new minor version is released in the Kubernetes main repository. -* 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. +A consequence of this is that `client-go` version numbers will be unrelated to +Kubernetes version numbers. + +#### 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. -* **client-go/1.5** 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.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