cmd/go: tidy behavior regarding ignore tag is hard to find

[mem]

What operating system and processor architecture are you using (go env)?

go env Output

$ go env
not applicable

What did you do?

I was working with ruleguard, which recommends to use the ignore tag to exclude rules form the build.

Quoting from https://github.com/quasilyte/go-ruleguard/blob/master/README.md?plain=1#L72

// +build ignore

package gorules

import "github.com/quasilyte/go-ruleguard/dsl"
...

ruleguard fails to run because the package github.com/quasilyte/go-ruleguard/dsl is not listed in the main module's go.mod file and because of the way it works, it needs to have this package available.

After running:

go get github.com/quasilyte/go-ruleguard/dsl

ruleguard works.

But after running go mod tidy, ruleguard fails again.

Going over go.mod, the package is no longer listed.

What did you expect to see?

The package github.com/quasilyte/go-ruleguard/dsl is still present in go.mod after running go mod tidy.

What did you see instead?

The package github.com/quasilyte/go-ruleguard/dsl is gone from go.mod after running go mod tidy.

It turns out the problem is that go mod tidy will handle the ignore tag in a different way, as mentioned in https://go.dev/ref/mod#go-mod-tidy, which is referenced from the output of go help mod tidy:

go mod tidy works by loading all of the packages in the main module and all of the packages they import, recursively. This includes packages imported by tests (including tests in other modules). go mod tidy acts as if all build tags are enabled, so it will consider platform-specific source files and files that require custom build tags, even if those source files wouldn’t normally be built. There is one exception: the ignore build tag is not enabled, so a file with the build constraint // +build ignore will not be considered. Note that go mod tidy will not consider packages in the main module in directories named testdata or with names that start with . or _ unless those packages are explicitly imported by other packages.

The detail about ignore is not minor, and it should be more readily available.

[mem]

I should be more clear:

This is the output of go help mod tidy:

go help mod tidy
usage: go mod tidy [-e] [-v] [-go=version] [-compat=version]

Tidy makes sure go.mod matches the source code in the module.
It adds any missing modules necessary to build the current module's
packages and dependencies, and it removes unused modules that
don't provide any relevant packages. It also adds any missing entries
to go.sum and removes any unnecessary ones.

The -v flag causes tidy to print information about removed modules
to standard error.

The -e flag causes tidy to attempt to proceed despite errors
encountered while loading packages.

The -go flag causes tidy to update the 'go' directive in the go.mod
file to the given version, which may change which module dependencies
are retained as explicit requirements in the go.mod file.
(Go versions 1.17 and higher retain more requirements in order to
support lazy module loading.)

The -compat flag preserves any additional checksums needed for the
'go' command from the indicated major Go release to successfully load
the module graph, and causes tidy to error out if that version of the
'go' command would load any imported package from a different module
version. By default, tidy acts as if the -compat flag were set to the
version prior to the one indicated by the 'go' directive in the go.mod
file.

See https://golang.org/ref/mod#go-mod-tidy for more about 'go mod tidy'.

The detail about how go mod tidy handles ignore should be available here, not behind the link.

[gopherbot]

Change https://go.dev/cl/430136 mentions this issue: cmd/go/internal/modcmd: expand help text for go mod tidy

[mem]

The alternative fix is to change the help text in go help buildconstraint, which reads:

To keep a file from being considered for the build:

        //go:build ignore

(any other unsatisfied word will work as well, but "ignore" is conventional.)

because that is not true: ignore is NOT just a convention, it's handled differently by the compiler:

https://github.com/golang/go/blob/master/src/cmd/go/internal/imports/build.go#L188

If that is preferred, I would still propose that the help text for go help mod tidy should be changed to include a link to go help buildconstraint.

[seankhliao]

cc @bcmills