Add Dependency matrix to README #337
There are no files selected for viewing
| Original file line number | Diff line number | Diff line change |
|---|---|---|
|
|
@@ -16,6 +16,7 @@ will give you head and doesn't handle the dependencies well. | |
| - [Compatibility: your code <-> client-go](#compatibility-your-code---client-go) | ||
| - [Compatibility: client-go <-> Kubernetes clusters](#compatibility-client-go---kubernetes-clusters) | ||
| - [Compatibility matrix](#compatibility-matrix) | ||
| - [Dependency matrix](#dependency-matrix) | ||
| - [Why do the 1.4 and 1.5 branch contain top-level folder named after the version?](#why-do-the-14-and-15-branch-contain-top-level-folder-named-after-the-version) | ||
| - [Kuberentes tags](#kubernetes-tags) | ||
| - [How to get it](#how-to-get-it) | ||
|
|
@@ -124,6 +125,41 @@ Key: | |
| * `=` Maintenance is manual, only severe security bugs will be patched. | ||
| * `-` Deprecated; please upgrade. | ||
|
|
||
| #### Dependency Matrix | ||
| Since there are multiple libraries that client-go is either required to, or can work | ||
| with, this is a list of all the libraries and versions that work with each other. | ||
|
|
||
| | client-go | [apimachinery](https://github.com/kubernetes/apimachinery) | [apiextensions-apiserver](https://github.com/kubernetes/apiextensions-apiserver)<sup>*</sup> | [code-generator](https://github.com/kubernetes/code-generator)<sup>+</sup> | | ||
|
There was a problem hiding this comment. I'd prefer splitting the form into libraries that depend on client-go (e.g., apiextensio-apiserver, apiserver, kube-aggregator), and libraries that client-go depends on (apimachinery, api). For the latter, this README should point out that the versions recorded in Godeps/Godeps.json is the ground truth. And There was a problem hiding this comment. In addition to agreeing with everything Chao says here ( :) ) I am worried that this documentation may quickly diverge. Instead of listing a table, can we say something more along the lines of: There was a problem hiding this comment.
I read that just as an example. So it cannot really diverge. I think a table is easier to consume, but I am fine with @lavalamp's proposed sentence as well. There was a problem hiding this comment. Actually we have something very similar already: Only the link to the semver tags is missing in that paragraph. |
||
| | ----------------------------------| -----------------------------------------------------------|----------------------------------------------------------------------------------------------|----------------------------------------------------------------------------| | ||
| | tag: v5.0.x | tag: kubernetes-1.8.x | tag: kubernetes-1.8.x | tag: kubernetes-1.8.x | | ||
|
There was a problem hiding this comment. I have mixed feelings about making client-go v5.0.2 if kubernetes-1.8.2 and kuberentes-1.8.1 don't have any diff regarding the client. WDYT? There was a problem hiding this comment. I would create it just to simplify the versioning, even if just saying that nothing changed. There was a problem hiding this comment. At the very least I do not want to see v5.0.2 against kubernetes-1.8.4 because nothing changed. These versions must stay in sync for simplicity. |
||
| | tag: v6.0.x | tag: kubernetes-1.9.x | tag: kubernetes-1.9.x | tag: kubernetes-1.9.x | | ||
|
|
||
| <sup>*</sup> optional library that exposes the Extensions API, for example, for | ||
| Custom Resource Definitions. | ||
|
There was a problem hiding this comment. Add: "This appears here temporarily, as the API types / client are not yet available separately." There was a problem hiding this comment. How about: It means a developer doesn't have to know what an API type / client means in this context. How does that sound? There was a problem hiding this comment. I'm hesitant to add this here, at least until such a change is finalised and documented. There is already developer concern over client-go's high rate of breaking changes. Is there a specific reason we should warn people that a change is coming in the future, before we know what that change is? There was a problem hiding this comment. I wouldn't pre-announce any future change here either. When we move the API, we will annoucne that in the release notes. Let's describe the current situation. |
||
| <sup>+</sup> optional library for generating Kubernetes style API types. Typically | ||
| used with Custom Resource Definitions. | ||
|
|
||
| Note that `x` versions need to align. For example tag v.5.0.1 in client-go, will be | ||
| supported with tag kubernetes-1.8.1 in apimachinery and other repositories | ||
|
|
||
| Using the git tag versions is the preferred way of managing dependencies for newer | ||
| releases of client-go, and since client-go is backward compatible, it is recommended that | ||
| developers always use the latest version. | ||
|
There was a problem hiding this comment. This paragraph doesn't seem to be necessary? The compatibility matrix states what version of client-go a user needs. |
||
|
|
||
| For releases <= v4.0.x of client-go (kubernetes-1.7.x), it is required to use one of these | ||
|
There was a problem hiding this comment. These three paragraphs seem to duplicate the https://github.com/kubernetes/client-go/blob/master/INSTALL.md. If you take my earlier suggestion regarding splitting the form into libraries that depend on client-go and client-go's dependencies, we don't need these paragraphs. There was a problem hiding this comment. True. INSTALL.md has much more info already than I thought. What does it mean? Is it too hard to find? There was a problem hiding this comment. So, I have to admit - I totally missed that there was a INSTALL.md and the links to it in the page. Maybe a dependency matrix is overkill given the INSTALL.md - having at least a list of the potential dependent libraries (apimachinery, apiextensions-apiserver, code-generator) somewhere for discoverability is useful - maybe just add the extra links to the Kubernetes tags section. WDYT? If so, I may just close this PR, and start a fresh one. Or should there be a more expansive list - something like (with links):
That could make it easier to know what pieces to look for where. I think this maybe a nice addition. WDYT? There was a problem hiding this comment. A list below "What's included" would certainly fit. |
||
| tools to get a supported version of client-go and associated libraries if you have a | ||
| requirement to do so. | ||
|
|
||
| Client-go specifies non-optional libraries in its Godeps/Godeps.json file. While | ||
| [Glide](https://glide.sh) will respect these automatically, with | ||
| [godep](https://github.com/tools/godep) you have to manually `godep restore` | ||
| them from client-go's directory and then `godep save` them in your project. | ||
|
There was a problem hiding this comment. Why is a There was a problem hiding this comment. It's the same we say in INSTALL.md. Of course, one can work in package in the GOPATH alone, then no |
||
|
|
||
| Note that [golang/dep](https://github.com/golang/dep) currently | ||
| **does not respect the specified dependencies in client-go**. | ||
| You have to manually add them as constraints in your `Gopkg.toml` for all its | ||
| dependencies (not only for k8s.io/api and k8s.io/apimachinery!). | ||
|
|
||
| #### Deprecation policy | ||
|
|
||
| We will maintain branches for at least six months after their first stable tag | ||
|
|
||
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I would prefer not to make this in the form of a chart. I would say, "here are the dependency libraries you might need:
<list>; corresponding commits are all tagged withkubernetes-x.x.xtags. If you use godep or glide you should not need to know this."I would especially avoid mentioning e.g.
release-1.6branch in the apimachinery repo, as IMO it is not versioned yet and I don't want people to expect that pattern to continue--it should switch to a semver system like client-go.There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
But we need to give people an approach that works now, and for older (1.7 and lower) releases, the release branch is the only thing that exists in apimachinery.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
People starting fresh shouldn't use the older releases. People not starting fresh already have something that works and don't have this problem.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Sorry, I don't understand this logic - are we assuming that there are no <= 1.7 kubernetes clusters that want to use client-go in the future?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Newer client releases are backwards compatible, so basically, yes, I don't see why you would start out using something not the latest.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Fair enough - then the simplification we've discussed further down will make more sense.