cmd/go: replace directives are not thoroughly documented

[heschi]

What version of Go are you using (go version)?

$ go version
go version devel +f0c383b833 Wed May 1 16:53:19 2019 +0000 linux/amd64

Does this issue reproduce with the latest release?

Yes

What did you do?

Read go help modules and go help go.mod.

What did you expect to see?

Some discussion of what replacements are and what they do.

What did you see instead?

The only documentation I can find is these lines in go help go.mod:

	replace bad/thing v1.4.5 => good/thing v1.4.5

	replace, to replace a module version with a different module version.
Exclude and replace apply only in the main module's go.mod and are ignored
in dependencies.  See https://research.swtch.com/vgo-mvs for details.

I think there's probably more to say about how replace works. For example, it doesn't explicitly state that the thing to replace is on the left side of the arrow. It also doesn't mention that the version on the left is optional.

[shivi28]

Hello @heschik Can I pick up this task

[heschi]

@jayconrod or @bcmills would be the ones to review it, and they might be pretty busy getting 1.13 ready, so there might be a bit of delay on the review. For my part I say go for it.

[bcmills]

A CL to document the existing behavior would be fine, but note that for Go 1.14 we're planning to both revamp the semantics of replace directives (#26904) and reorganize the modules documentation.

[gopherbot]

Change https://golang.org/cl/220080 mentions this issue: design/36460: add design for lazy module loading

[bcmills]

We should also note that replace replaces the source code of the given version, rather than retargeting requirements on the given version to instead require something else.