Document what the best supported path for using client-go is

[jbeda]

Posted this to slack but putting it here too.

Right now it is very confusing as to what users should do to have the best experience using this library.

The README says:

If you use go get to get client-go, you will get the unstable master branch! You can git checkout a stable branch.

We recommend using a vendor tool, like godep, glide, or govendor to track a stable version of client-go.

But then it also says that, wrt the 1.4 and 1.5 branches: "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." This makes it sound like these branches are deprecated.

And then there is a 2.0 branch. But that isn't documented anywhere that I can find and it isn't clear what the plan is. This obviously isn't matching up with the kubernetes version so that's a bit confusing.

Ideally, active development should happen on a branch so that the master branch always works (#90). But if we are going to keep it on a branch, the "how to get it" should be more explicit. Something like:

The best way to use client-go is to explicitly take a dependency on a versioned branch. As go get doesn't support branches it'll be a bit of a process to get the latest stable version installed. The latest stable version is on the 1.5 branch. To install do the following:

go get ...
cd ...
git co ....
go get ./...

To save most other users from the pain of dealing with this, you should probably use a tool like godep to vendor the client-go dependency.

I'm not sure what the steps are here as I'm still figuring them out. But it would be useful if I didn't have to.

[jbeda]

Here is what I did to get something that looks like it might work (assuming one dir in GOPATH)

go get k8s.io/client-go
cd $GOPATH/src/k8s.io/client-go
git checkout release-1.5
cd 1.5
godep restore ./...
cd $GOPATH/src/<my-pkg>
godep save ./...

I have no idea if this is right or not but seems to at least build with the 1.5 client.

Also note that this'll clobber whatever versions you might have in your GOPATH.

[sttts]

/cc @caesarxuchao @lavalamp @deads2k

[seh]

Related: #83.

[caesarxuchao]

Thanks for the suggestion. I'll update the README for branch 2.0, and the commands on "how to get" the branch.

[jbeda]

I still haven't gotten an answer to this question: what is the 2.0 branch? What is the purpose there? how does that differ from head? None of this is written down anywhere I can find.

[lavalamp]

@caesarxuchao I'm writing an extensive document on how to install this thing.

@jbeda I can only document things so fast, sorry, thanks for being patient. There's not yet a 2.0.0 (i.e., non-alpha) tag, so feel free to pretend it doesn't exist yet.

[lavalamp]

@jbeda please take a look at #106.

[lavalamp]

@jbeda also #108.