Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

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

Open
mdwhatcott opened this Issue Oct 15, 2018 · 14 comments

Comments

Projects
None yet
8 participants
@mdwhatcott
Copy link

mdwhatcott commented Oct 15, 2018

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

@elliotforbes

This comment has been minimized.

Copy link

elliotforbes commented Oct 15, 2018

I wouldn't mind giving this one a shot?

@ianlancetaylor

This comment has been minimized.

Copy link
Contributor

ianlancetaylor commented Oct 16, 2018

@thepudds

This comment has been minimized.

Copy link

thepudds commented Dec 23, 2018

@andybons @bcmills This might be somewhat stuck with some type of CLA-related issue? See for example #28218 (comment). 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

This comment has been minimized.

Copy link
Member

andybons commented Dec 23, 2018

I’ve responded on the Pull Request.

@gopherbot

This comment has been minimized.

Copy link

gopherbot commented Dec 23, 2018

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

@thepudds

This comment has been minimized.

Copy link

thepudds commented Dec 24, 2018

@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

This comment has been minimized.

Copy link

elliotforbes commented Dec 24, 2018

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

This comment has been minimized.

Copy link
Member

andybons commented Dec 28, 2018

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

This comment has been minimized.

Copy link
Member

andybons commented Jan 7, 2019

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

This comment has been minimized.

Copy link

elliotforbes commented Jan 7, 2019

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

@andybons

This comment has been minimized.

Copy link
Member

andybons commented Jan 7, 2019

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

@elliotforbes

This comment has been minimized.

Copy link

elliotforbes commented Jan 12, 2019

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

This comment has been minimized.

Copy link

thepudds commented Jan 28, 2019

@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

This comment has been minimized.

Copy link
Member

bcmills commented Jan 28, 2019

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.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
You can’t perform that action at this time.