cmd/go: add documentation for go.work.sum

[samherrmann]

With the release of Go 1.18, we now have workspaces. From my findings, workspaces appear to be documented in the following locations:

• https://go.dev/doc/gopath_code#Workspaces
• https://go.dev/doc/tutorial/workspaces
• https://github.com/golang/go/blob/go1.18/src/cmd/go/internal/workcmd/work.go

None of these locations however make mention of the go.work.sum file. The go.work.sum file was however described in the proposal.

This issue is to bring the description of the go.work.sum file from the proposal into the official documentation.

[mknyszek]

CC @matloob

[codyoss]

I recently added go.work to a large project and another maintainer asked me about the sum file and it left me a bit clueless as well. Seems oddly missing from https://go.dev/ref/mod#workspaces

[mvrahden]

I agree, a little piece of documentation on the purpose of this file and its insides would be great.

[MarianMacik]

I also came across a few situations where the go.work.sum file changes seemingly for no reason, even shrinking in size despite new modules were added to the workspace. So I would appreciate some documentation about its purpose.

[calebschoepp]

I also came across a few situations where the go.work.sum file changes seemingly for no reason, even shrinking in size despite new modules were added to the workspace. So I would appreciate some documentation about its purpose.

I've been really struggling with this myself. My go.work.sum seems to be constantly changing. I don't understand the purpose of it, why its changing, and whether it is something I should track in git.

[gopherbot]

Change https://go.dev/cl/563855 mentions this issue: _content/ref/mod: document go.work.sum files

[matloob]

I sent out CL 563855 to add documentation to golang.org/ref/mod, which seems to be the best place for it.

@calebschoepp Usually go.work files shouldn't be checked in, so go.work.sum files shouldn't be checked in either. But if you are checking in your go.work file it makes sense to check in the go.work.sum file for consistency for the same reason that a go.sum is checked in: to guarantee that others doing a build in your repo are getting the same results. Maybe we could add a line about that to the text proposed for 53502.