cc @bcmills

Yep, I'm still writing the full doc.

@bcmills Is there a draft version available anywhere?

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.)

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?

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

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.

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)?