Go: website: Update "How to Write Go Code" with go modules

[mdwhatcott]

Now that go modules are a thing, is it time to update "How to Write Go Code" with information about modules?

[elliotforbes]

I wouldn't mind giving this one a shot?

[ianlancetaylor]

CC @robpike

[thepudds]

@andybons @bcmills This might be somewhat stuck with some type of CLA-related issue? See for example https://github.com/golang/go/pull/28218#issuecomment-430628733. Is there someone you could suggest who could help unstick the CLA issue? Or is there some other approach you might recommend like deleting the PR and trying again in the hopes of avoiding whatever tripped up the CLA bot?

[andybons]

I’ve responded on the Pull Request.

[gopherbot]

Change https://golang.org/cl/142297 mentions this issue: doc/code.html: update code.html to use go modules

[thepudds]

@elliotforbes @mdwhatcott @deanveloper Thanks for helping make this a reality!

Several months ago, I think the plan or hope was that GO111MODULE would default to on by 1.12, and I suspect this issue and at least the initial work here might have started under that premise?

It now seems for multiple reasons GO111MODULE will still default to auto in 1.12 (i.e., preserving old GOPATH behavior by default in 1.12), and now the plan is to default to on in 1.13.

Reading through the comments in this issue and the PR and CL, I initially thought your intent was to update "How to Write Go Code" to be a modules-specific document, and to drop the details of older GOPATH behavior... but now after reading through more of the CL, I am not sure if that was the intent?

My personal take is:

• it might be that trying to explain _both_ GOPATH and modules in a single document that targets someone new to Go might be adding more complexity than it is worth.
• given the default behavior in 1.12, it is probably premature (at least for now) to _only_ have a modules-specific version of "How to Write Go Code" (without the GOPATH details for someone who still needs or wants to use GOPATH for whatever reason).

Together, that might seem to imply there could be two versions of this document – a new version that is modules-specific, and one that is the current GOPATH-specific version.

However, I am not sure of the best approach, so more than anything I wanted to ask what you might be currently thinking...

Finally, note that I'm basically just a random member of the community, so please do not give too much weight to anything I say here or in the CL (and instead just view my comments as coming from a peer in the community).

[elliotforbes]

Ok, I can update the code to remove the GOPATH explanations and focus purely on using modules. This could then be tagged to go live with the 1.12 release in February?

Does this sound like a plan?

[andybons]

Generally, documentation fixes are permitted during the freeze so it’s feasible this will get in by the time 1.12 stable is released. No need to worry about that.

Let’s wait for @bcmills to respond. Many people are out this week for the holidays so we’ll need to be a bit patient. Thanks.

[andybons]

After discussion with the team, we don't believe we should be removing references to GOPATH as modules are not on by default (and even then, GOPATH will be around for some time).

[elliotforbes]

Cool, should I leave as-is then? Or are there more actions for me to take at this point?

[andybons]

The current doc changes replace GOPATH with modules. Ideally we'd want them both to be there.

[elliotforbes]

I've taken an initial stab at explaining how both work in the same document, I'll be going over it more once I have a bit of free time this weekend, but it's up if you want to critique the approach used.

[thepudds]

@andybons Do you know if there is still time for this to land in time for 1.12?

Also, there is some nuance here. This is not a complete list of open questions, but for example:

• Should this document encourage someone new to Go to use modules for new projects, or should it be completely neutral on that question?
• Should there be a complete discussion of how to set up a multi-module workspace, or perhaps instead just something like ~1-2 sentences along with pointers for more details?
• Is it ok to mention rogpeppe/gohack?
• Is it ok to mention other resources from the broader community, vs. should this particular document only reference the official documentation, which would primarily be the cmd/go documentation at this point?
• Should the GOPATH and modules discussion be largely interwoven, vs. more separated?

There is a longer list of questions, and I'm not suggesting all open questions be answered immediately. Rather, I am listing those example questions primarily to suggest there is a healthy chance that ultimately more than one person on the core Go team might want to weigh in on this effort.

In general, there is a natural cadence to open source development that often involves waiting (e.g., waiting for someone to have something initially ready for feedback, waiting for it to get to the top of a reviewer's stack, waiting to find time to incorporate latest feedback, etc.), and patience is certainly a virtue in all of this...

...but I also wonder:

1. Would it be possible to identify someone from the core Go team to help shepherd this along, including giving early feedback?
2. Would it make sense to try to identify at least an approximate set of who on the core Go team is likely to want to weigh in this document?
3. Would it then be possible to work backwards from the final "drop dead date" for this to hit 1.12 to identify perhaps a couple of interim milestones (e.g., making this up, but perhaps something like "By date X, complete initial review and be ready for final broader review")?

Or if not exactly something like that, then perhaps some other small amount of orchestration that could help increase the odds of this landing in time for 1.12?

CC @bcmills @heschik

[bcmills]

There is realistically no way this will land for 1.12, but we should make sure it is updated for 1.13.

I think that discussion of gohack and broader resources are probably better kept elsewhere: “How to Write Go Code” is a quick-start document, currently standing at only ~6 pages of text, and I'd like to keep it that way. (A link to the Modules wiki page alongside the other reference links at the end is probably a good idea, though.)

I would rather see GOPATH and modules as separate sections (or separate views) than interspersed: someone getting started in module mode mostly shouldn't care about GOPATH, and we don't want to make a lot of work to disentangle them again when GOPATH mode goes away.

[amnonbc]

This document should target beginners.
So all vestiges to the legacy GOPATH, keeping all your code in a single workspace etc. should be removed.

[jadekler]

FYI this is underway at https://go-review.googlesource.com/c/website/+/199417.

[gopherbot]

Change https://golang.org/cl/199417 mentions this issue: content/static/doc: rewrite code.html for go modules

[gopherbot]

Change https://golang.org/cl/213937 mentions this issue: content/static: add gopath_code.html file and regenerate