github/client-go
1
0
Fork 0
mirror of https://github.com/kubernetes/client-go.git synced 2025-06-26 07:02:01 +00:00
Code Issues Projects Releases Wiki Activity

Update README to explain versioning better

Browse Source
This commit is contained in:
Daniel Smith 2017-02-14 16:15:21 -08:00
parent 86a2be1b44
commit a0a777840a
2 changed files with 78 additions and 12 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

13
CHANGELOG.md
View File

@ -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

77
README.md
View File

@ -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