Join GitHub today
GitHub is home to over 40 million developers working together to host and review code, manage projects, and build software together.Sign up
cmd/go: give library/tool maintainers advice on how to word READMEs during modules transition #27233
Please answer these questions before submitting your issue. Thanks!
What version of Go are you using (
@wsc1 I might not be following, but the normal workflow when you are starting a fresh module is to first create a
Are you asking to flip that sequence, and/or make
In general, when running a command like
Possibly semi-related: one aspect that might catch people by surprise is if the GO111MODULE environment variable is explicitly set to GO111MODULE=on, then getting a tool via something like
Part of the overall issue is that modules are currently opt-in, and a full solution for operating outside of all modules will likely wait until GO111MODULE=on becomes the default behavior. See #24250 and #24250 (comment) for more related discussion, including this comment from there:
Sorry if this is not directly on target...
I have been playing them and following the discussion and started using them in some projects, so I'm not a modules noob (eg I know what go.mod and go.sum store), but there are certainly details I'm not aware of.
Since operating "outside" a module is the entry point on very many project pages that I've seen: "use: go get a/b/....". (no module specified). I would consider it unfortunate to exclude browsing/touring of go projects from the normal work flow with GO111MODULE=on. I would encourage it also to be made as simple/untricky as possible with modules as soon as possible, so people aren't turned away by such problems. That would produce more uses and thus give modules functionality more of a solid basis on which to move out of "preliminary" status.
I also do not think anyone can really define what "the normal workflow" is, I thought the issue tracker was to inform those manning it what the workflows are, not the other way around, and modules are moreover preliminary.
Thanks for your pointers to the other issues operating outside a module for go1.12. It seems to me to be essentially the same problem conceptually, In view of those issues and the timeline, we may update the project pages documentation relying on modules so as not to give users impression "go get" works out of the box, which is unfortunate. If y'all considered changing the behaviour of go get with GO111MODULE=on so it does something reasonable, it would smooth things out for us in this respect.
Hi @wsc1, at the start of my comment, I was trying to describe the normal workflow "when starting a fresh module".
I 100% agree it is a shock when
It is a significant way people are "stubbing their toes" on modules.
That said, I believe the plan is for
Here is one sample statement about "clearly this must work eventually" from #24250 (comment):
And of course, things work more as expected if you temporarily do
In short, I agree with what you are saying that
(As far as I understand things, anyway... and I'm happy to learn more if my understanding is off).
Sounds like we're understanding each other better!
One thing particular to my case is I'm involved in some projects which have decided to use modules collectively (and non-nested). As a result, the development process can be much facilitated in terms of allowing independence between the projects, because modules will find the right dependencies between them and the heads can be out of sync. All that is great, as in this scenario the independence between heads seems very much necessary.
But old style go-get won't work for us reliably or even often because this independence/desynchronisation at the heads will be too common. This puts us in a bit of an awkward position w.r.t. go get and modules, perhaps more so than projects which have one module. It would be nice to say to those involved "we use modules." and not "we use modules, so you have to do blah=auto and GOPATH=.... and cwd=...."
So in this kind of setup, a collection of inter-related, non-nested modules is perhaps a new use case to consider. But it may also help provide insight into how interdependent projects using single modules will interact -- there may be a similar need for them as well to say to their users that go get needs modules, especially if using them to interact with other projects, and they might also prefer just saying "use modules" as compared to listing all the requirements under GO111MODULE=auto.
I'll keep an eye out in case y'all decide and have resources to address go get with GO111MODULE=on before 1.12.
As an update,
It seems GO111MODULE=auto is just as difficult to get working with module aware go get as GO111MODULE=on.
Below is what we put in our dev README. Any other ideas/comments?
should work whether or not heads are desynchronised.
Then set GO111MODULE=on for go build, go test, etc.
@wsc1 My own experience: If you work in module-aware mode (
@dolmen Thanks, sounds good if you have a main.go or other entry point in mind before working with the module.
At least in my experience, when I want to look at and play with some project, I usually don't have enough information to have a main.go or other module in mind.
But your idea may serve as a useful template for some examples...
#24250 covers the case of a "global" install of a command/tool with
If you are in a module context then
Otherwise if you are in
I'm going to retitle this issue to be more about what advice we should give package/tool maintainers on how to word their READMEs during the transition (@thepudds and I discussed such an issue, I can't find one for now), because this point has come up on multiple occasions.
A fix for #24250 should make it into the 1.12 release. If the
Given that, I don't think most maintainers should need to update their READMEs at all, but please do let me know if I've missed something.