Thanks for the request.

I took the liberty of removing the proposal label, since I don't think this is something that needs to be handled with the proposal process. You've just made a reasonable request for some new documentation, after all.

CC @myitcv @thepudds

@bcmills @myitcv

If we focus on someone new to Go, I think in a pre-module world these types of questions might be best answered by the introductory golang.org "How to Write Go Code" page? (There are also plenty of great introductory books, blogs, videos, etc., but that might be the best single document within the official documentation for these types of questions?)

There is an issue #28215 for updating that for modules, and I had seen that making progress, but looks like it might be stuck right now with a CLA issue. (I just added a comment there regarding that).

If we focus on someone new to Go, in this interim 1.11/1.12 period with modules defaulting to off, it might be best to have two documents:

1. If someone does not yet want to use modules: "How to Write Go Code" (the existing document)
2. If someone wants to use modules: "How to Write Go Code with Modules" (or some other title representing some new document that covers similar ground in a modules world)

The two documents could point to each other with 2-3 introductory sentences to help someone decide which one they want to read.

Or said another way, I would guess trying to explain both GOPATH and modules in a single document targeting someone new to Go would probably add more complexity than it is worth, and it seems premature (at least right now) to only have a modules-only version of "How to Write Go Code"?

I think some documents on golang.org are tied to the Go release cycle, but other documents are updated outside the release cycle. I'm not sure which category describes "How to Write Go Code".

In any event, to help fill in the vacuum a bit in the most immediate term, I guess I would propose:

• Create a new wiki page titled something like "How to Write Go Code (with Modules)" or something along those lines.
• Use the CL from website: Update "How to Write Go Code" with go modules #28215 as a starting point for populating it.
• Indicate along the top that it is a draft.
• Try to get some help from the community to get it into reasonable shape.
• Eventually, the content there gets deleted with a pointer to the 'real' "How to Write Go Code" whenever that is ready.

Alternatively, perhaps there is a plan to have the 'real' module documentation targeting new Go users popping out in the near-ish term, in which case an interim wiki page would not be not as useful.

I will say, though, there seems to be some hunger within the ecosystem for official modules documentation targeting new Go users, so maybe an interim wiki page could help bootstrap the material?

Does that sound reasonable? Or alternative suggestions?

@shaunc

Regarding your questions above, here is a rough and non-comprehensive attempt to answer.

This is not an answer to your primary request for a "Modules from the ground up" targeting someone new to Go. That would be longer, and doesn't quite exist (at least not in an official form that is a polished as the current non-module introductory "How to Write Go Code" official page). Rather, this is quick attempt to answer your more specific sub-questions above.

First of all, for most projects it is best to at least start with one overall go.mod in your repository, and not put a go.mod file in each folder. It adds substantially more complexity to have multiple go.mod files in a given repository. If you have been working with a mono-repo, you likely can work with a single module.

A more detailed answer below (which I'm collapsing for now, so you need to click on "Longer Answer")...

There is much more that could be said, or said better, but my main question for you would be -- if you read that longer answer below, what are your next 3-4 most immediate questions (which might be re-asking one of your initial questions, or might be a follow-up question, etc.)?

module github.com/my/thing

require (
    github.com/some/dependency v1.2.3
    github.com/another/dependency/v4 v4.0.0
)

repo/
├── go.mod
├── bar
│   └── bar.go
└── foo
    └── foo.go

import "example.com/my/module/mypkg"

@thepudds -- Thanks!

In the intervening days I more or less figured this out, but its great to have a description in one place to refer to.

My initial confusion, not related to my question, as it is covered in the existing doc, was not understanding the tight coupling between packages and folders. (I thought of packages something like C++ namespaces -- in theory orthogonal to file layout. Perhaps I was led in this direction
by the fact that applications have a "main" package that is not named for the folder. If I have a
library with an executable utility script, I reasoned, one could have both "main" and "foo" packages
in same directory, so folders were an organizational convenience.... Anyway I sorted that out but existing documents could perhaps be clearer about package/folder and "main" as exception.)

The monorepo currently is a mix of typescript and python, with a bit of cython. In fact this initial experiment is to replace a cython-backed service with go, as cython is hard to maintain.

One thing I like about the node/typescript tooling, which I understand you don't (yet?) have, is that you can have one overall "package.json" for the monorepo as a whole then individual ones for subprojects, and require() looks up the tree for dependencies. Thus you can mostly maintain one overall set of dependencies, saving work and gnashing of teeth because of incompatibilities, while still being able to override when you need to. (NB -- don't know if support for this is on the horizon; it could be alternately with an "extends" directive in go.mod if you don't like implicit dependency on filesystem hierarchy.)

Anyway -- thanks to you and the go community!

We now have quite a bit of module documentation at https://go.dev/doc.

I'm sure it could be further improved and clarified, but I would rather we file more targeted individual issues for the remaining improvements.