Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

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

myitcv opened this issue Nov 4, 2018 · 8 comments

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

myitcv opened this issue Nov 4, 2018 · 8 comments


Copy link

myitcv commented Nov 4, 2018

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?


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

go env Output
$ go env
GOGCCFLAGS="-fPIC -m64 -pthread -fmessage-length=0 -fdebug-prefix-map=/tmp/go-build925002674=/tmp/go-build -gno-record-gcc-switches"


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, 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
Results for

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:

cc @rsc @bcmills @thepudds @rogpeppe @mvdan

@gopherbot gopherbot added this to the Proposal milestone Nov 4, 2018
@myitcv myitcv added the modules label Nov 4, 2018
Copy link

mvdan commented Nov 5, 2018

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.

Copy link
Member Author

myitcv commented Nov 5, 2018


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.

@myitcv myitcv changed the title proposal: module repository check tool proposal: module repository health check tool Nov 5, 2018
Copy link

mvdan commented Nov 5, 2018

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

Copy link

bcmills commented Nov 5, 2018

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

Copy link
Member Author

myitcv commented Nov 5, 2018

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!

Copy link
Member Author

myitcv commented Nov 28, 2018

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.

Copy link

thepudds commented Jan 16, 2019

@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:

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:
  • gomodvet-005: using a prerelease version:
  • gomodvet-006: using a pseudoversion version:
  • 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.

Copy link

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.

@ianlancetaylor ianlancetaylor added this to Incoming in Proposals (old) Feb 24, 2021
@rsc rsc changed the title proposal: module repository health check tool proposal: cmd/go: add module repository health check tool Aug 10, 2022
@bcmills bcmills added the GoCommand cmd/go label Mar 13, 2023
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Status: Incoming

No branches or pull requests

6 participants