Skip to content

Commit

Permalink
Update README for release 1.17
Browse files Browse the repository at this point in the history
  • Loading branch information
@nikhita
nikhita committed Dec 11, 2019
1 parent bc9b51d commit a34a405
Showing 1 changed file with 54 additions and 51 deletions.
105 changes: 54 additions & 51 deletions README.md
View file
Expand Up @@ -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.

Expand Down Expand Up @@ -44,16 +45,17 @@ 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
- 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). However, a bump in the
minor version _may_ be accompanied by backward-incompatible changes.
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.

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.
Expand All @@ -63,23 +65,21 @@ 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 incompatible changes can be expected at
different versions.

See [INSTALL.md](INSTALL.md) for guidelines on requiring a specific
version of client-go.

#### Compatibility: client-go <-> Kubernetes clusters

Expand All @@ -92,16 +92,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:

Expand All @@ -122,19 +118,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:
Expand All @@ -161,14 +159,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
Expand All @@ -179,7 +182,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.
Expand Down

0 comments on commit a34a405

Please sign in to comment.