cmd/go: standardize on the term "work module" in help docs & error messages

[natefinch]

In some help text and error output of the go command, the term "main module" gets used, which is very easy to confuse with "package main". I had this confusion when reading #44840. In that thread it was suggested by @ianthehat that maybe the terminology should change, and I think this is a very good idea.

package main has existed since the beginning of Go's life, meaning the package that is the entrypoint for a go binary, and the existence of which tells the go command to produce such a binary.

The term main module .... is very unclear to me. I think it means "that module you specified on the command line when using the go command"? But, the module you specified might not be a package main and thus this error is confusingly worded. Using the same descriptor for both is confusing.

The minimum bar would be to call it any thing except main. current or primary would be acceptable suggestions IMO. However, I don't think there exists a single term that would be clear enough on its own in that error message (and probably anywhere else) to not require further explanation or added context.

Ideally, we'd also rewrite these error messages to be more human-readable for people who aren't go experts.

Here's an example from the above-linked issue:

current:

go install bitbucket.org/jatone/genieql@latest: bitbucket.org/jatone/genieql@v0.0.0-20210306180040-be9c7b630c18
	The go.mod file for the module providing named packages contains one or
	more replace directives. It must not contain directives that would cause
	it to be interpreted differently than if it were the main module.

proposed:

go install bitbucket.org/jatone/genieql@latest: bitbucket.org/jatone/genieql@v0.0.0-20210306180040-be9c7b630c18
	The go.mod file for the above-named module contains one or more replace directives
	which differ from the replace directives in the go.mod file for the current module
	(github.com/you/project). When imported as a dependency, any replace directives in 
	bitbucket.org/jatone/genieql's go.mod would be ignored, causing it to be built with 
	different dependencies than its author intended.

diff:
bitbucket.org/jatone/genieql@v0.0.0-20210306180040-be9c7b630c18:
  replace github.com/traefik/yaegi => github.com/james-lawrence/yaegi v0.14.3-modules-enh-tag
github.com/you/project:
  <no replace directive for github.com/traefik/yaegi>

(This is an example of an attempt at making the error message more clear and helpful. Obviously, the exact message could be different.)

Yes, this is longer, but it's more human-readable, and gives more specific information about a fairly confusing build problem. It tells you what "current module" refers to. It tells you why it's bad that the replace directives are different, using more clear language than "interpreted differently". Finally, it tells you exactly what replace directives are different right in the terminal.

This is sooo much more clear and helpful than our current error message.

[dmitshur]

CC @bcmills, @matloob.

[seankhliao]

in #57001 @rsc uses "work module"

[StevenACoffman]

Define the “work module” as the one containing the directory where the go command is run. We sometimes call this the “main module”, but I am using “work module” in this document for clarity.

Or rather, the nearest ancestor directory to your current working directory containing a go.mod.

So anywhere inside of the scope of your go.mod module, you can run go mod why <something> and get the same output.

[matloob]

We've settled on the term "work module" to represent this concept.

[mvdan]

I'm a bit surprised by the choice of "work module"; I would have expected "current module" to be more intuitive to most users. Is the choice of "work" to mimic "working directory", or to follow the term "workspace" from go.work and go help work?

[matloob]

The choice was inspired by "working directory".