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

doc: introduce a page for CI best practices #42119

Open
mvdan opened this issue Oct 21, 2020 · 7 comments
Open

doc: introduce a page for CI best practices #42119

mvdan opened this issue Oct 21, 2020 · 7 comments

Comments

@mvdan
Copy link
Member

@mvdan mvdan commented Oct 21, 2020

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
Copy link
Member Author

@mvdan mvdan commented Oct 21, 2020

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
Copy link
Member

@bcmills bcmills commented Oct 21, 2020

@bcmills bcmills added this to the Backlog milestone Oct 21, 2020
@mvdan
Copy link
Member Author

@mvdan mvdan commented Nov 18, 2020

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
Copy link
Contributor

@jayconrod jayconrod commented Nov 18, 2020

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
Copy link

@stevetraut stevetraut commented Nov 18, 2020

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
Copy link
Member Author

@mvdan mvdan commented Nov 18, 2020

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
Copy link
Contributor

@rsc rsc commented Nov 19, 2020

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

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
Linked pull requests

Successfully merging a pull request may close this issue.

None yet
6 participants