cmd/go: go list -u -m upgrade behaviour should be better documented

[rogpeppe]

go version go1.14.4 linux/amd64

The go list -m -u command (and also go get with no explicit version) does not always suggest an upgrade to the latest available version number. In this case, the commit date for jmoiron/sql@v1.2.0 is earlier than the commit date for the current pseudo-version, but it's not clear from the documentation, which says:

When the latest version of a given module is newer than
the current one, list -u sets the Module's Update field
to information about the newer module.

whether "newer" means "later version number" (in which case I'd expect it to suggest v1.2.0) or "latest commit date" (in which case the suggestion is right). If it really is "latest commit date", then I'd be concerned about backports - a backport of a fix from a later version could then prevent automatic upgrades to the appropriate latest version.

I think this could at least use some clarification in the docs.

Here's a reproducer for the issue (run with the testscript command):

# I'd expect go list to list upgrades for both modules,
# to v1.2.0 and v 1.0.0 respectively.
# However it seems to ignore the available
# sqlx upgrade for some reason.
go list -m -u github.com/jmoiron/sqlx github.com/heetch/sqalx
cmp stdout expect-go-list

# Check that go get can actually see the upgrade.
go get github.com/jmoiron/sqlx@v1
cmp stderr expect-go-get
-- expect-go-list --
github.com/jmoiron/sqlx v0.0.0-20190426154859-38398a30ed85
github.com/heetch/sqalx v0.4.0 [v1.0.0]
-- expect-go-get --
go: github.com/jmoiron/sqlx v1 => v1.2.0
go: downloading github.com/jmoiron/sqlx v1.2.0
-- foo.go --
package m

import (
	_ "github.com/heetch/sqalx"
	_ "github.com/jmoiron/sqlx"
)
-- go.mod --
module m

go 1.15

require (
	github.com/heetch/sqalx v0.4.0
	github.com/jmoiron/sqlx v0.0.0-20190426154859-38398a30ed85
)
-- go.sum --
github.com/DATA-DOG/go-sqlmock v1.3.3 h1:CWUqKXe0s8A2z6qCgkP4Kru7wC11YoAnoupUKFDnH08=
github.com/DATA-DOG/go-sqlmock v1.3.3/go.mod h1:f/Ixk793poVmq4qj/V1dPUg2JEAKC73Q5eFN3EC/SaM=
github.com/davecgh/go-spew v1.1.0/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38=
github.com/davecgh/go-spew v1.1.1 h1:vj9j/u1bqnvCEfJOwUhtlOARqs3+rkHYY13jYWTU97c=
github.com/davecgh/go-spew v1.1.1/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38=
github.com/go-sql-driver/mysql v1.4.0 h1:7LxgVwFb2hIQtMm87NdgAVfXjnt4OePseqT1tKx+opk=
github.com/go-sql-driver/mysql v1.4.0/go.mod h1:zAC/RDZ24gD3HViQzih4MyKcchzm+sOG5ZlKdlhCg5w=
github.com/golang/protobuf v1.2.0/go.mod h1:6lQm79b+lXiMfvg/cZm0SGofjICqVBUtrP5yJMmIC1U=
github.com/heetch/sqalx v0.4.0 h1:itQcEQuDY7GuUbSt4+urrRTNDWhM9bh9lJLWxnImqPQ=
github.com/heetch/sqalx v0.4.0/go.mod h1:E94nHyvfKEeIbbcHTc7eZSifTAOLES5Kz8gU04iZIgc=
github.com/jmoiron/sqlx v0.0.0-20190426154859-38398a30ed85 h1:+LZtdhpMITOXE+MztQPPcwUl+eqYjwlXXLHrd0yWlxw=
github.com/jmoiron/sqlx v0.0.0-20190426154859-38398a30ed85/go.mod h1:1FEQNm3xlJgrMD+FBdI9+xvCksHtbpVBBw5dYhBSsks=
github.com/lib/pq v1.0.0 h1:X5PMW56eZitiTeO7tKzZxFCSpbFZJtkMMooicw2us9A=
github.com/lib/pq v1.0.0/go.mod h1:5WUZQaWbwv1U+lTReE5YruASi9Al49XbQIvNi/34Woo=
github.com/mattn/go-sqlite3 v1.9.0 h1:pDRiWfl+++eC2FEFRy6jXmQlvp4Yh3z1MJKg4UeYM/4=
github.com/mattn/go-sqlite3 v1.9.0/go.mod h1:FPy6KqzDD04eiIsT53CuJW3U88zkxoIYsOqkbpncsNc=
github.com/pmezard/go-difflib v1.0.0 h1:4DBwDE0NGyQoBHbLQYPwSUPoCMWR5BEzIk/f1lZbAQM=
github.com/pmezard/go-difflib v1.0.0/go.mod h1:iKH77koFhYxTK1pcRnkKkqfTogsbg7gZNVY4sRDYZ/4=
github.com/rogpeppe/fastuuid v1.1.0 h1:INyGLmTCMGFr6OVIb977ghJvABML2CMVjPoRfNDdYDo=
github.com/rogpeppe/fastuuid v1.1.0/go.mod h1:jVj6XXZzXRy/MSR5jhDC/2q6DgLz+nrA6LYCDYWNEvQ=
github.com/stretchr/objx v0.1.0/go.mod h1:HFkY916IF+rwdDfMAkV7OtwuqBVzrE8GR6GFx+wExME=
github.com/stretchr/testify v1.3.0 h1:TivCn/peBQ7UY8ooIcPgZFpTNSz0Q2U6UrFlUfqbe0Q=
github.com/stretchr/testify v1.3.0/go.mod h1:M5WIy9Dh21IEIfnGCwXGc5bZfKNJtfHm1UVUgZn+9EI=
golang.org/x/net v0.0.0-20180724234803-3673e40ba225/go.mod h1:mL1N/T3taQHkDXs73rZJwtUhF3w3ftmwwsq0BUmARs4=
golang.org/x/text v0.3.0/go.mod h1:NqM8EUOU14njkJ3fqMW+pc6Ldnwhi/IjpwHt7yyuwOQ=
google.golang.org/appengine v1.4.0 h1:/wp5JvzpHIxhs/dumFmF7BXTf3Z+dd4uXta4kVyO508=
google.golang.org/appengine v1.4.0/go.mod h1:xpcJRLb0r/rnEns0DIKYYv+WjYCduHsrkT7/EB5XEv4=

[jayconrod]

This is working as intended, but the documentation for go list and go get doesn't explain well enough what's happening. That should be improved in the module reference documentation at least (#33637).

go list -m -u, go get with no specific version specified, and go get -u all use the @upgrade version query. @upgrade is like @latest, but if the current version is semantically higher than the version matched by @latest (for example, a newer pre-release), or if the current version is a pseudo-version with a chronologically later commit date, then @upgrade matches the current version instead of the @latest version.

[rogpeppe]

That should be improved in the module reference documentation at least

Yes, I'm now sure that this is doing the right thing, but it was confusing to me even after I'd read through the docs. Rather than closing it, I'll retitle this issue to something a bit more specific than #33637 because ISTM that this particular aspect of the docs might easily fall between the cracks again.