x/website: doc/modules/pruning lacks content

[whereswaldon]

What version of Go are you using (go version)?

$ go version
go version go1.17.2 linux/amd64

Does this issue reproduce with the latest release?

Yes

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

go env Output

$ go env
GO111MODULE=""
GOARCH="amd64"
GOBIN=""
GOCACHE="/home/chris/.cache/go-build"
GOENV="/home/chris/.config/go/env"
GOEXE=""
GOEXPERIMENT=""
GOFLAGS=""
GOHOSTARCH="amd64"
GOHOSTOS="linux"
GOINSECURE=""
GOMODCACHE="/home/chris/Code/go/pkg/mod"
GONOPROXY=""
GONOSUMDB=""
GOOS="linux"
GOPATH="/home/chris/Code/go"
GOPRIVATE=""
GOPROXY="https://proxy.golang.org,direct"
GOROOT="/home/chris/.local/lib/go-1.17.2"
GOSUMDB="sum.golang.org"
GOTMPDIR=""
GOTOOLDIR="/home/chris/.local/lib/go-1.17.2/pkg/tool/linux_amd64"
GOVCS=""
GOVERSION="go1.17.2"
GCCGO="gccgo"
AR="ar"
CC="gcc"
CXX="g++"
CGO_ENABLED="1"

What did you do?

I updated the version of a package we depend upon and ran go mod tidy.

What did you expect to see?

I expected to see nothing, or an error pointing me to documentation explaining the error.

What did you see instead?

proprietaryproject.com/internal/assets tested by
        proprietaryproject.com/internal/assets.test imports
        github.com/stretchr/testify/assert imports
        gopkg.in/yaml.v3 loaded from gopkg.in/yaml.v3@v3.0.0-20200615113413-eeeca48fe776,
        but go 1.16 would select v3.0.0-20210107192922-496545a6307b

To upgrade to the versions selected by go 1.16:
        go mod tidy -go=1.16 && go mod tidy -go=1.17
If reproducibility with go 1.16 is not needed:
        go mod tidy -compat=1.17
For other options, see:
        https://golang.org/doc/modules/pruning

I don't understand the problem, so I followed the link at the bottom of the error: https://golang.org/doc/modules/pruning

That link redirects to https://golang.org/doc/modules/managing-dependencies, which contains no information about these -compat and -go flags. It also doesn't contain the word prune anywhere.

So my report is really a documentation bug. I'm confused by the decision that go is making, and the resource the CLI points me to does not help. Did the contents of that page change recently or something?

[seankhliao]

cc @bcmills

[bcmills]

Yep, I'm still writing the full doc.

[whereswaldon]

@bcmills Is there a draft version available anywhere?

[bcmills]

Not yet. (What I'm working on is basically a tutorial on exclude, replace, and Go 1.17 module graph pruning.)

In the meantime, though, I'm happy to advise on specific cases. (Generally if you're not sure it's easiest to just take the upgrade: go mod tidy -go=1.16 && go mod tidy -go=1.17.)

[jbardin]

Hi @bcmills,

What I'm finding confusing in the output is that go1.17 won't upgrade the transitive dependencies, but then complains about the transitive dependency versions. The cli suggestion is to use -go=1.16, but we've made the decision to not support go1.16 by specifying go1.17. The output also says that if go1.16 compatibility isn't needed to use -compat=go1.17, but that does not fix the go.mod and go mod tidy still fails.

I guess my questions is that if go mod tidy -go=1.16 && go mod tidy -go=1.17 does the right thing here, why do I need to use "go1.16 mode" when I don't need to support go1.16? Is it because somewhere in the dependency tree there is a go.mod with go1.16?

[bcmills]

The cli suggestion is to use -go=1.16, but we've made the decision to not support go1.16 by specifying go1.17.

The complete suggestion is to use -go=1.16 followed by -go=1.17.
go mod tidy -go=1.16 updates the selected versions to what Go 1.16 would select.
go mod tidy -go=1.17 then changes it back to satisfy the 1.17 invariants, at which point the dependencies should be stable.

(That is: go mod tidy should not downgrade them once they have been upgraded in this way. If that is not the case, please file a separate issue with steps to reproduce.)

The output also says that if go1.16 compatibility isn't needed to use -compat=go1.17, but that does not fix the go.mod and go mod tidy still fails.

It should not “fix the go.mod” because there is nothing broken about it if you do not care about compatibility.
However, if you take that option you need to use -compat=go1.17 flag at every go mod tidy, because the -compat flag is not preserved in the go.mod file.

(It exists in order to facilitate the one-time 1.16-to-1.17 transition for projects that test against all supported Go versions, so it didn't seem worth adding a permanent go.mod directive.)

if go mod tidy -go=1.16 && go mod tidy -go=1.17 does the right thing here, why do I need to use "go1.16 mode" when I don't need to support go1.16?

Without the -compat flag, the go tool has no way to know that you do not need to support consumers of the module on Go 1.16 or earlier.

However, you can indicate that you really don't care about the transitive requirement using an exclude directive:

exclude gopkg.in/yaml.v3 v3.0.0-20210107192922-496545a6307b

[jbardin]

Thanks for the clarification @bcmills!

Without the -compat flag, the go tool has no way to know that you do not need to support consumers of the module on Go 1.16 or earlier.

I think this is where I was confused. I thought that specifying go 1.17 in go.mod did this, removing the need for the -compat flag. I agree that manual step of some sort needs to be taken here, but we started with a go1.17-only go.mod, updated a dependency using go1.17, then suddenly go mod tidy is failing to work without first upgrading as go1.16.

[mohammed90]

I've come across the same issue and eventually found the content at https://go.dev/ref/mod#graph-pruning. Shouldn't the URL reported in the error message be https://go.dev/ref/mod#graph-pruning instead of https://golang.org/doc/modules/pruning (which redirects to https://go.dev/doc/modules/managing-dependencies)?