docs: provide some common vendoring tips/pitfalls

[tmc]

sharing some information about how folks approach vendoring with different tools and perhaps noting some gotchas would be valuable for users.

[deejross]

I can tell you from a Glide perspective, I've been trying to get this to work all day. Etcd wants a version of golang/protobuf from 2016 without a Filename field that gRPC-Go wants, gRPC-Go hasn't released v1.2.2 yet with the new Context methods that the current gRPC-Gateway v1.2.2 is looking for the new Context methods.

This is exactly the type of thing Semantic Versioning is supposed to be preventing. I get that you might be trying to match up the version numbers with gRPC-Go, but unfortunately, this introduced a backwards-incompatible change that vendoring tools see as just a simple patch, when in fact, it should have been a major version since it breaks everything unless you manually specify each version number for all the packages.

[deejross]

Also would like to point out that I'm using gRPC-Go v1.2.1, gRPC-Gateway v1.2.0 and I'm now getting a bunch of errors similar to these:

pb/mydis.pb.gw.go:775: too many arguments in call to runtime.AnnotateContext
	have ("github.com/deejross/mydis/vendor/golang.org/x/net/context".Context, *runtime.ServeMux, *http.Request)
	want ("github.com/deejross/mydis/vendor/golang.org/x/net/context".Context, *http.Request)

So I can't get this working at all.

[tamalsaha]

@deejross, I believe your *.gw.go files were generated from the gateway plugin from master branch. You need to regenerate the *.gw.go files using gateway plugin v1.2.0.

The generated *.gw.go file format was changed recently by #336 in master branch.

[deejross]

@tamalsaha I believe that's correct. The plugins are installed per the documentation:

go get -u github.com/golang/protobuf/{proto,protoc-gen-go}
go get -u google.golang.org/grpc

I think that installs from the master. Is there a better method of installing the correct version of the plugins? I have multiple developers, plus a Jenkins build environment that would all need to have the same version of these plugins. To my knowledge, Glide does not install binary files in $GOPATH/bin the way that go get does, but I could be mistaken.

[tamalsaha]

We use shall scripts to get specific version of gateway and install its plugins. You can find our script here: https://github.com/appscode/api/blob/master/hack/builddeps.sh#L53

Please note, this script installs our forked version with some additional changes. I meant to show this as an example.

[deejross]

I learned quite a bit from this, it was very helpful. Basically, you install using go get -u per the instructions, cd into each directory (i.e. $GOPATH/src/github.com/grpc-ecosystem/grpc-gateway), do a git checkout with the desired tag/version, and finally go install the binaries to $GOPATH/bin.

While not the most straightforward way to install the desired version of plugins, it should work for our needs. Thanks a bunch! Hopefully, Go's dep tool can solve issues like these in the future.

[rhnasc]

@deejross do you know if there's an issue on dep(or a specification maybe) regarding this new capability you just referred to? This is a feature that would certainly come in handy in situations like these.

[deejross]

@rhnasc I think the major issue here, which most package managers aim to fix, is that go get does not support versions. If dep can replace go get for downloading to $GOPATH/src and generating binaries in $GOPATH/bin as well as acting as a vendoring tool, then it would probably fix what happened here, or at least make it easier to fix.