ref/mod: add a warning against checking in go.work files

Add a warning against checking in go.work files together with a
sentence about where it might be okay.

Fixes golang/go#53502

Change-Id: I1f643fc75c2951a9dcd56db11d612989dadcaa59
Reviewed-on: https://go-review.googlesource.com/c/website/+/580115
Reviewed-by: Eli Bendersky‎ <eliben@golang.org>
LUCI-TryBot-Result: Go LUCI <golang-scoped@luci-project-accounts.iam.gserviceaccount.com>
Reviewed-by: Alan Donovan <adonovan@google.com>
Reviewed-by: Sam Thanawalla <samthanawalla@google.com>

1 files changed, 19 insertions, 0 deletions

diff --git a/_content/ref/mod.md b/_content/ref/mod.md
index 6abdf7c5..d222f72e 100644
--- a/_content/ref/mod.md
+++ b/_content/ref/mod.md
@@ -1216,6 +1216,25 @@ package can be used by Go programs to make the same changes programmatically.
 The go command will maintain a `go.work.sum` file that keeps track of hashes used by the workspace
 that are not in collective workspace modules' go.sum files.
 
+It is generally inadvisable to commit go.work files into version control
+systems, for two reasons:
+
+* A checked-in `go.work` file might override a developer's own `go.work` file
+  from a parent directory, causing confusion when their `use` directives don't
+  apply.
+* A checked-in `go.work` file may cause a continuous integration (CI) system to
+  select and thus test the wrong versions of a module's dependencies. CI systems
+  should generally not be allowed to use the `go.work` file so that they can test
+  the behavior of the module as it would be used when required by other modules,
+  where a `go.work` file within the module has no effect.
+
+That said, there are some cases where committing a `go.work` file makes sense.
+For example, when the modules in a repository are developed exclusively with
+each other but not together with external modules, there may not be a reason the
+developer would want to use a different combination of modules in a workspace.
+In that case, the module author should ensure the individual modules are tested
+and released properly.
+
 ### Lexical elements {#go-work-file-lexical}
 
 Lexical elements in `go.work` files are defined in exactly the same way [as for