Repository: go
Issue: cmd/go: go list -u -m upgrade behaviour should be better documented
Labels: Documentation,NeedsInvestigation,modules

`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](https://github.com/rogpeppe/go-internal/tree/master/cmd/testscript)):

```
# 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=
```