proposal: cmd/go: add module repository health check tool

[myitcv]

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

$ go version
go version go1.11.1 linux/amd64

Does this issue reproduce with the latest release?

n/a

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

go env Output

$ go env
GOARCH="amd64"
GOBIN=""
GOCACHE="/home/myitcv/.cache/go-build"
GOEXE=""
GOFLAGS=""
GOHOSTARCH="amd64"
GOHOSTOS="linux"
GOOS="linux"
GOPATH="/home/myitcv/gostuff"
GOPROXY=""
GORACE=""
GOROOT="/home/myitcv/gos"
GOTMPDIR=""
GOTOOLDIR="/home/myitcv/gos/pkg/tool/linux_amd64"
GCCGO="gccgo"
CC="gcc"
CXX="g++"
CGO_ENABLED="1"
GOMOD=""
CGO_CFLAGS="-g -O2"
CGO_CPPFLAGS=""
CGO_CXXFLAGS="-g -O2"
CGO_FFLAGS="-g -O2"
CGO_LDFLAGS="-g -O2"
PKG_CONFIG="pkg-config"
GOGCCFLAGS="-fPIC -m64 -pthread -fmessage-length=0 -fdebug-prefix-map=/tmp/go-build925002674=/tmp/go-build -gno-record-gcc-switches"

Details

A number of issues and Slack and go-nuts questions boil down to a VCS repository being in some way "invalid" as far as modules are concerned. An incomplete list includes:

• go.mod for a v >= 2 module not having a /v2 suffix
• tags that are not semver compatible
• go.mod incomplete (i.e. the result of go mod tidy not committed)
• transitive dependencies leaking through to the main module because a dependency's go.mod is not complete
• Whether a version is compatible with Go pre 1.9.7 or 1.10.3
• ...

I think it might be useful to develop a tool that can be run against an arbitrary (remote) VCS repository that catches these sorts of problems, but also provides a summary of what is valid. A health check if you will.

This would be a tool for authors as well as consumers, because indicating (perhaps via one of those GitHub README badges) that your repository is module-safe is a good state and signal. Indeed in time this might be something that would sit well on godoc.org/similar, but in the short term a command line tool would have significant value.

These checks could of course be heavily cached (somewhere central).

This is a very rough idea, so just posting for thoughts/feedback:

$ modanalyse https://github.com/myitcv/terrible
Results for https://github.com/myitcv/terrible:

Semver issues:
    0.0.1 is not compatible with Go modules; should be v0.0.1
    0.0.1alpha is not a valid pre-release

Module completeness:
    v0.0.3 is missing a go.sum
    v0.0.4 has an incomplete go.mod

Invalid releases:
    v2.0.0 invalid because go.mod does not end with /v2

Valid releases:
    v0.0.2
    v1.0.0
    v2.0.1

cc @rsc @bcmills @thepudds @rogpeppe @mvdan

[mvdan]

Have you thought about integrating some or all of these into go release? #26420

The upside is that we wouldn't need a separate command or service for this, and we'd have a single command to ensure that all modules conform to a certain standard.

The downside is that users need to trust that authors are using the command when doing each release. Perhaps we could let users run the checks themselves too, e.g. go release -check some/module.

[myitcv]

@mvdan

Have you thought about integrating some or all of these into go release? #26420

Yes that did indeed cross my mind (but I failed to reference #26420). Rightly or wrongly I thought I'd start discussion about the "health check" separately. But we can/should fold this issue into #26420 in case that's more appropriate.

[mvdan]

I agree discussion should start separately to begin with. There's some overlap with that issue, but they're certainly not duplicates.

[bcmills]

Haven't thought about the features, but go mod vet seems like the obvious name. 🙂

[myitcv]

Haven't thought about the features, but go mod vet seems like the obvious name. 🙂

Assuming the mod command isn't going anywhere, sounds good!

[myitcv]

Much like we have golint separate from go vet, it might also make sense to have a repository linter:

• someone coming from a more Java background might be tempted to put everything under src
• suggest putting commands in cmd/
• ...

These tests would surely be very fuzzy... but might be good enough.

Definitely a separate tool.

Just noting the idea here for now.

[thepudds]

@myitcv has mentioned multiple times that a tool such as he describes above could be built outside of the core go tool to start.

FYI, this weekend, I put together a very rough cut of something in this ballpark: https://github.com/thepudds/gomodvet

It is very much WIP / prototype level, but wanted to at least mention it. In particular, this first cut was helpful this past weekend to concretely illustrate to some people that some sanity checking is possible to at least increase the odds of catching someone accidentally stepping on some potential modules-related landmines.

gomodvet currently has 8 notable things it finds (that is, 8 "rules"):

• gomodvet-001: the current module's go.mod file would be updated by 'go build'
• gomodvet-002: a module has multiple major versions in this build
• gomodvet-003: module "foo" was required with potential incompatible versions: v0.9.0, v1.0.0
• gomodvet-004: using a version excluded by another module: github.com/go-chi/chi@v1.0.1
• gomodvet-005: using a prerelease version: github.com/go-chi/chi@v4.0.0-rc2
• gomodvet-006: using a pseudoversion version: github.com/go-chi/chi@v0.0.0-20151106203253-e413833c12f1
• gomodvet-007: dependencies have available updates
• gomodvet-008: the current module uses 'replace' directives

Most of those are not strictly speaking "problems" in all cases, but most of those are at least notable situations. (E.g., a module with multiple major versions in a build might be a conscious choice, or might be because someone is doing import "foo/v3" in one spot and accidentally doing import "foo" in another spot).

You can control what you do / don't want to be told about via a command line flag for each rule.

The current gomodvet might have more overlap with #26420 than some of the specific modanalyse ideas outlined in the discussion above, but wanted to post here first, including because this issue here is a bit more low-key and has more brainstorm-style discussion.

The intent of gomodvet is mainly experimentation -- ideally anything useful in gomodvet would land in an ultimate go release or go mod vet (or otherwise somewhere in the go tool).

edit: the public gomodvet repo was slightly behind when this comment was first posted, but now it has the latest version with 8 rules.

[samsalisbury]

This would be really useful, there are module maintainers out there who publish unusable, or difficult to use modules at the moment. Currently, they sometimes refuse to fix the problems even when pointed out, because they are not affecting that team's ability to write code, just other teams' ability to consume it. If there were an official go tool that could call out this kind of problem, then it could provide a concrete bug to report to maintainers which might help the ecosystem become more usable. Even better if it detected breaking API changes and suggested using the vN+1-beta pattern so maintainers knew there was a way out and they did have the option to make breaking/experimental changes without damaging the ecosystem.