doc: introduce a page for CI best practices

[mvdan]

Most CI scripts and defaults do just the basics: go test ./...

There are many more commands that likely make sense for a majority of projects, and some are well known, but we don't have a single place to document and maintain them well. For example:

• Enforce gofmt from a specific version of Go, e.g. test -z $(gofmt -l .)
• Use go test -race ./... to catch data races in tests
• Use go vet ./..., since go test only runs a subset of go vet
• Use go mod tidy and ensure that there aren't changes to go.mod or go.sum (via go mod tidy -mod=readonly maybe?)
• Use go mod verify to ensure that go.sum agrees with what's in the module cache
• Use go test -run=- -bench=. -benchtime=1x ./... to catch stale benchmarks (see #41824)

And potentially staticcheck ./... too, since it's now sort of recommended by gopls as an extension to go vet. Though note that this should be a small set of recommendations that most projects should follow, so it shouldn't include an endless list of linters that might be interesting to some users.

We should include a ready-to-use script containing all of the recommended steps, for example in POSIX Shell. We could document each step directly via script comments, meaning that the entire thing could be copy-pasted and self-documenting.

I'm happy to kickstart this work during the freeze. /cc @bcmills @jayconrod @myitcv @jadekler

[mvdan]

The reason I want this to be a doc on the main site or the main repo is two-fold: so that it's code reviewed (so the wiki doesn't work), and so that it can be maintained and updated over time (so a blog post doesn't work).

[bcmills]

CC @stevetraut

[mvdan]

Friendly bump - who should I get the green light from for this document? I think the freeze is probably the best time to work on docs, so I'd like to start writing this doc before the end of the year.

If no green light is needed I can just start writing and send a CL, but I'd rather not do that if the decision will likely be "we don't want this doc in the website" :)

[jayconrod]

Our tech writer @stevetraut would be the best person to coordinate with. He's in the process of writing a programmer's guide to Go with many different topics. I think CI best practices would fit into that nicely.

[stevetraut]

Sorry for the late response, folks.

@mvdan Thanks for the idea! I think it could be useful content. I'm not sure it's within the "programming with Go" focus that the programmer's guide Jay mentioned has, but content aimed at team development would be useful. Currently, though, the guide is still taking shape and we're not sure yet what's in and what's out.

May I suggest that you add it to the wiki? That would get it in front of folks right away. And I'm sure I'll be collecting other content and ideas from the wiki along the way, and may add a topic on CI.

@rsc

[mvdan]

Thanks for the response. I honestly don't think the wiki is the best place, because it's not code-reviewed and anyone can edit it, so it's not a good place to document best practices. That is the reason why I opened #34038 last year, though unfortunately the process is taking a long time. That's why I was hoping this new document could be added directly to a git repository or the main site.

I could always start writing it while we decide where it goes, but I still think it has relatively less value (and can't be properly maintained) if it ends up in the wiki.

[rsc]

@mvdan, you're right that the wiki isn't the right long-term place, and we agree. But we have limited attention, and right now this specific page is not at the top of our list. We don't even have the framework set up for where the page would properly go. So if you want to publish something now, the wiki is still the best place. Long term, we'll have a better answer.