From 1132e72f6cdf991b5b3f79cac52dbf580639178c Mon Sep 17 00:00:00 2001 From: Nikhita Raghunath Date: Fri, 6 Dec 2019 15:57:45 +0530 Subject: [PATCH] Update README for release 1.17 --- README.md | 105 +++++++++++++++++++++++++----------------------------- 1 file changed, 49 insertions(+), 56 deletions(-) diff --git a/README.md b/README.md index 44499b51..890c683e 100644 --- a/README.md +++ b/README.md @@ -2,7 +2,8 @@ Go clients for talking to a [kubernetes](http://kubernetes.io/) cluster. -We recommend using the `kubernetes-1.x.y` tag matching the current Kubernetes release (`kubernetes-1.15.3` at the time this was written). +We recommend using the `v0.x.y` tags for Kubernetes releases >= `v1.17.0` and +`kubernetes-1.x.y` tags for Kubernetes releases < `v1.17.0`. See [INSTALL.md](/INSTALL.md) for detailed installation instructions. `go get k8s.io/client-go@master` works, but will fetch `master`, which may be less stable than a tagged release. @@ -44,42 +45,31 @@ See [INSTALL.md](/INSTALL.md) for detailed installation instructions. ### Versioning -`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. +- For each `v1.x.y` Kubernetes release, the major version (first digit) +would remain `0`. -Changes that add features in a backwards-compatible way will result in bumping -the minor version (second digit) number. - -Bugfixes will result in the patch version (third digit) changing. PRs that are +- 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. -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 +We will create a new branch and tag for each increment in the 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. +The HEAD of the master branch in client-go will track the HEAD of the master +branch in the main Kubernetes repo. #### 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. 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. +The `v0.x.y` tags indicate that go APIs may change in incompatible ways in +different versions. + +See [INSTALL.md](INSTALL.md) for guidelines on requiring a specific +version of client-go. #### Compatibility: client-go <-> Kubernetes clusters @@ -92,16 +82,12 @@ We will backport bugfixes--but not new features--into older versions of #### Compatibility matrix -| | Kubernetes 1.9 | Kubernetes 1.10 | Kubernetes 1.11 | Kubernetes 1.12 | Kubernetes 1.13 | Kubernetes 1.14 | Kubernetes 1.15 | -|---------------------|----------------|-----------------|-----------------|-----------------|-----------------|-----------------|-----------------| -| client-go 6.0 | ✓ | +- | +- | +- | +- | +- | +- | -| client-go 7.0 | +- | ✓ | +- | +- | +- | +- | +- | -| client-go 8.0 | +- | +- | ✓ | +- | +- | +- | +- | -| client-go 9.0 | +- | +- | +- | ✓ | +- | +- | +- | -| client-go 10.0 | +- | +- | +- | +- | ✓ | +- | +- | -| client-go 11.0 | +- | +- | +- | +- | +- | ✓ | +- | -| client-go 12.0 | +- | +- | +- | +- | +- | +- | ✓ | -| client-go HEAD | +- | +- | +- | +- | +- | +- | +- | +| | Kubernetes 1.15 | Kubernetes 1.16 | Kubernetes 1.17 | +|-------------------------------|-----------------|-----------------|-----------------| +| `kubernetes-1.15.0` | ✓ | +- | +- | +| `kubernetes-1.16.0` | +- | ✓ | +- | +| `kubernetes-1.17.0`/`v0.17.0` | +- | +- | ✓ | +| `HEAD` | +- | +- | +- | Key: @@ -122,19 +108,21 @@ between client-go versions. | Branch | Canonical source code location | Maintenance status | |----------------|--------------------------------------|-------------------------------| -| 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 3.0 | Kubernetes main repo, 1.6 branch | = - | -| client-go 4.0 | Kubernetes main repo, 1.7 branch | = - | -| client-go 5.0 | Kubernetes main repo, 1.8 branch | = - | -| client-go 6.0 | Kubernetes main repo, 1.9 branch | = - | -| client-go 7.0 | Kubernetes main repo, 1.10 branch | = - | -| client-go 8.0 | Kubernetes main repo, 1.11 branch | =- | -| client-go 9.0 | Kubernetes main repo, 1.12 branch | =- | -| client-go 10.0 | Kubernetes main repo, 1.13 branch | ✓ | -| client-go 11.0 | Kubernetes main repo, 1.14 branch | ✓ | -| client-go 12.0 | Kubernetes main repo, 1.15 branch | ✓ | +| `release-1.4` | Kubernetes main repo, 1.4 branch | = - | +| `release-1.5` | Kubernetes main repo, 1.5 branch | = - | +| `release-2.0` | Kubernetes main repo, 1.5 branch | = - | +| `release-3.0` | Kubernetes main repo, 1.6 branch | = - | +| `release-4.0` | Kubernetes main repo, 1.7 branch | = - | +| `release-5.0` | Kubernetes main repo, 1.8 branch | = - | +| `release-6.0` | Kubernetes main repo, 1.9 branch | = - | +| `release-7.0` | Kubernetes main repo, 1.10 branch | = - | +| `release-8.0` | Kubernetes main repo, 1.11 branch | =- | +| `release-9.0` | Kubernetes main repo, 1.12 branch | =- | +| `release-10.0` | Kubernetes main repo, 1.13 branch | =- | +| `release-11.0` | Kubernetes main repo, 1.14 branch | ✓ | +| `release-12.0` | Kubernetes main repo, 1.15 branch | ✓ | +| `release-13.0` | Kubernetes main repo, 1.16 branch | ✓ | +| `release-14.0` | Kubernetes main repo, 1.17 branch | ✓ | | client-go HEAD | Kubernetes main repo, master branch | ✓ | Key: @@ -161,14 +149,19 @@ existing users won't be broken. This repository is still a mirror of [k8s.io/kubernetes/staging/src/client-go](https://github.com/kubernetes/kubernetes/tree/master/staging/src/k8s.io/client-go), -the code development is still done in the staging area. Since Kubernetes 1.8 -release, when syncing the code from the staging area, we also sync the Kubernetes -version tags to client-go, prefixed with "kubernetes-". For example, if you check -out the `kubernetes-1.15.3` tag in client-go, the code you get is exactly the -same as if you check out the `v1.15.3` tag in Kubernetes, and change directory to -`staging/src/k8s.io/client-go`. The purpose is to let users quickly find matching -commits among published repos, like -[sample-apiserver](https://github.com/kubernetes/sample-apiserver), +the code development is still done in the staging area. + +Since Kubernetes `v1.8.0`, when syncing the code from the staging area, +we also sync the Kubernetes version tags to client-go, prefixed with +`kubernetes-`. From Kubernetes `v1.17.0`, we also create matching semver +`v0.x.y` tags for each `v1.x.y` Kubernetes release. + +For example, if you check out the `kubernetes-1.17.0` or the `v0.17.0` tag in +client-go, the code you get is exactly the same as if you check out the `v1.17.0` +tag in Kubernetes, and change directory to `staging/src/k8s.io/client-go`. + +The purpose is to let users quickly find matching commits among published repos, +like [sample-apiserver](https://github.com/kubernetes/sample-apiserver), [apiextension-apiserver](https://github.com/kubernetes/apiextensions-apiserver), etc. The Kubernetes version tag does NOT claim any backwards compatibility guarantees for client-go. Please check the [semantic versions](#versioning) if @@ -179,7 +172,7 @@ you care about backwards compatibility. Use go1.11+ and fetch the desired version using the `go get` command. For example: ``` -go get k8s.io/client-go@kubernetes-1.15.3 +go get k8s.io/client-go@v0.17.0 ``` See [INSTALL.md](/INSTALL.md) for detailed instructions.