_content/doc: clarify that a replace directive does not imply require

This came up a couple times in Slack recently. I was confused about
this myself before we switched to -mod=readonly.

Change-Id: I3bafe347f4f9ecc3599e4b2568701422c95066c3
Reviewed-on: https://go-review.googlesource.com/c/website/+/322669
Trust: Jay Conrod <jayconrod@google.com>
Reviewed-by: Bryan C. Mills <bcmills@google.com>

2 files changed, 20 insertions, 0 deletions

diff --git a/_content/doc/modules/gomod-ref.md b/_content/doc/modules/gomod-ref.md
index 737327c7..351a7971 100644
--- a/_content/doc/modules/gomod-ref.md
+++ b/_content/doc/modules/gomod-ref.md
@@ -334,6 +334,20 @@ The `replace` directive can be useful in situations such as the following:
 * You've identified an issue with a dependency, have cloned the dependency's
   repository, and you're testing a fix with the local repository.
 
+Note that a `replace` directive alone does not does not add a module to the
+[module graph](/ref/mod#glos-module-graph). A [`require` directive](#require)
+that refers to a replaced module version is also needed, either in the main
+module's `go.mod` file or a dependency's `go.mod` file. If you don't have a
+specific version to replace, you can use a fake version, as in the example
+below. Note that this will break modules that depend on your module, since
+`replace` directives are only applied in the main module.
+
+```
+require example.com/mod v0.0.0-replace
+
+replace example.com/mod v0.0.0-replace => ./mod
+```
+
 For more on replacing a required module, including using Go tools to make the
 change, see:
 
diff --git a/_content/ref/mod.md b/_content/ref/mod.md
index 7c80750b..41f1181b 100644
--- a/_content/ref/mod.md
+++ b/_content/ref/mod.md
@@ -675,6 +675,12 @@ must match the module path it replaces.
 and are ignored in other modules. See [Minimal version
 selection](#minimal-version-selection) for details.
 
+Note that a `replace` directive alone does not add a module to the [module
+graph](#glos-module-graph). A [`require` directive](#go-mod-file-require) that
+refers to a replaced module version is also needed, either in the main module's
+`go.mod` file or a dependency's `go.mod` file. A `replace` directive has no
+effect if the module version on the left side is not required.
+
 ```
 ReplaceDirective = "replace" ( ReplaceSpec | "(" newline { ReplaceSpec } ")" newline ) .
 ReplaceSpec = ModulePath [ Version ] "=>" FilePath newline