proposal: ref/mod: mention whether go.work files should be checked into VCS

[mvdan]

https://go.dev/ref/mod#workspaces describes the current implementation of Go workspaces, as proposed by https://golang.org/issue/45713, which culminated in the proposal doc at https://go.googlesource.com/proposal/+/master/design/45713-workspace.md.

The proposal doc says:

go.work files should not be checked into version control repos containing modules so that the go.work file in a module does not end up overriding the configuration a user created themselves outside of the module. The go.work documentation should contain clear warnings about this.

However, the canonical documentation about go.work at https://go.dev/ref/mod#workspaces makes no mention of this, as far as I can see. In practice, it seems like the common knowledge among Go developers is that the file should never be checked in, because:

• GitHub's default gitignore includes the file since Go: Ignore Go workspace file go.work github/gitignore#3884
• Official Go repositories set an example by not checking them in; for example, x/tools does not include one, even though it has two modules connected by a directory replace directive
• Some third party docs or blog posts echo the recommendation to never check them in, like https://sebastian-holstein.de/post/2021-11-08-go-1.18-features/

First, we should decide whether we actually want to recommend users to never check in go.work files, like the original proposal doc said. If that's the case, then we simply need to add that recommendation to the /ref/mod page.

However, if we don't want to make that general recommendation, then we need to figure out under what circumstances it is recommended or not to check in go.work into VCS. For example, here are some personal guesses of mine:

• For a VCS repository holding a Go library module intended for external use, checking in go.work is likely a bad idea, as it prevents downstream users from easily setting up their own go.work in a parent directory.
• For large monorepos with multiple modules, it likely makes sense to check in go.work, as it makes the setup easier and often has no downsides.
• In some cases, go.work files will naturally live in the parent directory to the VCS clones, so they have no VCS repository to naturally be checked into at all.

cc @bcmills @marwan-at-work @matloob

[mvdan]

@bcmills points out that perhaps there isn't consensus about whether to check go.work files into VCS. We never gave any advice on it, and the community seems to lean on "never check them in".

We could recommend never checking them in, but I think that's a bad idea: in some particular scenarios it can make perfect sense to check them in, such as monorepos holding multiple modules.

We could continue with no recommendation at all, but I worry that then we'll continue to see third party docs and sites make assertive recommendations like "never check them in".

I personally think that we should give some general guidance that isn't too strict one way or another, such as:

go.work files should generally not be checked into VCS, as their purpose is to develop multiple modules at the same time, and each module tends to have its own VCS repository. However, there are certain scenarios where it can make sense to check in go.work files, such as a monorepo holding multiple modules which depend on each other.

This needs a decision that isn't easy to make, and we should probably get input from others, so @bcmills suggests turning this issue into a proposal. Doing that.