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

cmd/go: replace use of "main module" in help docs & error messages #58830

Open
natefinch opened this issue Mar 2, 2023 · 2 comments
Open

cmd/go: replace use of "main module" in help docs & error messages #58830

natefinch opened this issue Mar 2, 2023 · 2 comments
Labels
Documentation GoCommand cmd/go help wanted modules NeedsInvestigation Someone must examine and confirm this is a valid issue and not a duplicate of an existing one.
Milestone

Comments

@natefinch
Copy link
Contributor

natefinch commented Mar 2, 2023

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 dmitshur added NeedsInvestigation Someone must examine and confirm this is a valid issue and not a duplicate of an existing one. GoCommand cmd/go labels Mar 2, 2023
@dmitshur
Copy link
Contributor

dmitshur commented Mar 2, 2023

CC @bcmills, @matloob.

@dmitshur dmitshur added this to the Backlog milestone Mar 2, 2023
@seankhliao
Copy link
Member

in #57001 @rsc uses "work module"

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
Documentation GoCommand cmd/go help wanted modules NeedsInvestigation Someone must examine and confirm this is a valid issue and not a duplicate of an existing one.
Projects
None yet
Development

No branches or pull requests

5 participants