Google-cloud-go: README should note how to clone repo into GOPATH

[enocom]

For developers unfamiliar with the gotchas of vanity imports but used to cloning code from GitHub, the README should indicate how to clone the repo into the correct location within the GOPATH. Something like:

Cloned copies of this repository must be placed in the correct location in the GOPATH. Use:

git clone github.com/GoogleCloudPlatform/google-cloud-go $GOPATH/src/cloud.google.com/go

Or simply use the following command which will handle cloning the repo:

go get -u cloud.google.com/go

/cc @mainroach

[jadekler]

The README contains:

go get -u cloud.google.com/go/...

Does that not suffice?

[jba]

I haven't heard of a dev workflow that starts with a clone. People either use go get or a package manager.

I would say that if someone is sophisticated/DIY-ish enough to use git clone for Go development, they ought to be aware of how to map an import path to a directory. In addition to the go get line Jean mentioned, the readme also has import "cloud.google.com/go".

[mainroach]

I found this repo when investigating BigTable performance, which points to the loadtest tool. For someone unfamiliar with Golang, it was unclear what _exactly_ the right way to run that tool, or interact with this repo in order to do so. The documentation for the tool, and this repo were sparse enough that it remained unclear.

Google often links to github sample repos from their official documentation. For other GCP languages, git clone is the default action when linked to github (see python quickstart, or the java quickstart, or the php quickstart) As such, it's easy to get confused on if this repo was a samples repo, or something else.

If you're unfamiliar with GoLang, unfamiliar with how to use Google's Go client libraries, and unfamiliar with this repo; then the current language of the readme file doesn't provide help to point you in the right direction when you land here as a result of external links.

Also, the mention of go get is not descriptive enough for someone not familiar with golang (like myself). I just assumed it was a dependencies package manager (like npm or pip) and needed to be ran before you could execute the repo.

Perhaps a simple introduction would help? something like:

This repo contains the source code for the Google Cloud Go Client Libraries, which allow you to access GCP services using GoLang.

If you want to use these libraries in your project, please run go get -u cloud.google.com/go on your development machine, which should fetch and place them in the appropriate folder specified by your $GOPATH variable.

You do not need to clone this repo in order to use these APIs. If you're unfamiliar with Golang, and have been directed here in order to run a sample, or a tool, please see our official getting started documentation.

Again, my goal here is to just help clear up confusion for other people who might not be golang experts, and end up at this page for various reasons.

[jadekler]

For additional context, the loadtest tool seems to be referenced by:

I'm not convinced that the extra documentation is necessary. The only way you'd be able to use loaddtest.go would be to install Go, as part of which you'd presumedly learn about go get and $GOPATH.

Perhaps the problem in documentation is with the line item you linked, Colt? It may be disingenuous to refer to it as "the" loadtest tool instead of "a Go loadtest tool".

[mainroach]

The only way you'd be able to use loaddtest.go would be to install Go, as part of which you'd presumedly learn about go get and $GOPATH.

To be clear, I didn't install GoLang : I just loaded up the Google Cloud Console (which already has go installed) and just started typing. Maybe it's a reach to assume others would do the same, but it's worth pointing out that there does exist a path where you wouldn't learn those things.

It may be disingenuous to refer to it as "the" loadtest tool instead of "a Go loadtest tool".

Yes. I'd agree that the tool might be better served to be pulled out to a higher level repo, and better branded.

[jadekler]

To be clear, I didn't install GoLang : I just loaded up the Google Cloud Console (which already has go installed) and just started typing. Maybe it's a reach to assume others would do the same, but it's worth pointing out that there does exist a path where you wouldn't learn those things.

Ohhh. Gotcha. So, yeah, that's a nuisance for the user. It's loaded in your cloud console by sheer coincidence, and you're not guaranteed to be at HEAD. It's definitely a "maybe nice to have? but wholly unsupported" situation.

edit: If you did not have the cloud console option, do you think this confusion would be avoided? As in, user would have to go the google-cloud-go and run the necessary install Go + "go get" steps.

[mainroach]

Completely agreed that it's not the supported path. The suggested text would have saved me 2 hours of problems this morning. Given others may stumble here, I'd still support adding some nicer vocab to the readme help others find their way to the correct places.

[jadekler]

I remain unconvinced, and don't want to get in the business of tailoring our docs for explicitly unsupported usecases - however small the modifications. To prevent users from getting into this situation I'd rather remove the hacky go-client-libs-happen-to-exist-in-cloud-console situation.

I'll defer to @jba though.

[enocom]

How about instead of saying:

To install the packages on your system,

the README says,

To install the packages on your system, don't clone the repo and instead use:

Given Go's rapid growth, I expect we'll see more users stumble into this mistake. If a small change in wording makes this set of libraries (and GCP to a lesser extent) more user friendly, I'm in favor of the change.

[jadekler]

Should we do the same for protobuf? For grpc? The convention is very strongly towards using go get instead of git clone. I'm not sure that introducing a schism in convention makes things more use friendly.

[enocom]

If you as maintainer don't see this problem tripping up users, both hypothetically and experientially, I'm happy to close the issue.

[jadekler]

I think there's a valid in here that there's a route users can get tripped up by; I'm just saying that I don't think that go get is the issue, and that I'd rather have our docs or (more ideally) cloud shell experience be changed. I'm also hoping jba weighs in on this (he'll be back later today).

[jba]

If @enocom's suggested wording change would save someone two hours of stumbling, I'm all for it. I will make the change.