Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

cmd/go: replace directives are not thoroughly documented #32058

Closed
heschi opened this issue May 15, 2019 · 6 comments
Closed

cmd/go: replace directives are not thoroughly documented #32058

heschi opened this issue May 15, 2019 · 6 comments
Labels
Documentation GoCommand cmd/go modules NeedsFix The path to resolution is known, but the work has not been done.
Milestone

Comments

@heschi
Copy link
Contributor

heschi commented May 15, 2019

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.

@FiloSottile FiloSottile added the NeedsFix The path to resolution is known, but the work has not been done. label May 15, 2019
@FiloSottile FiloSottile added this to the Go1.13 milestone May 15, 2019
@andybons andybons modified the milestones: Go1.13, Go1.14 Jul 8, 2019
@shivi28
Copy link
Contributor

shivi28 commented Aug 2, 2019

Hello @heschik Can I pick up this task

@heschi
Copy link
Contributor Author

heschi commented Aug 2, 2019

@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
Copy link
Contributor

bcmills commented Aug 2, 2019

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
Copy link

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

gopherbot pushed a commit to golang/proposal that referenced this issue Mar 5, 2020
Updates golang/go#36460
Updates golang/go#27900
Updates golang/go#26955
Updates golang/go#30831
Updates golang/go#32058
Updates golang/go#32380
Updates golang/go#32419
Updates golang/go#33370
Updates golang/go#33669
Updates golang/go#36369

Change-Id: I1d4644e3e8b4e688c2fc5a569312495e5072b7d7
Reviewed-on: https://go-review.googlesource.com/c/proposal/+/220080
Reviewed-by: Russ Cox <rsc@golang.org>
@bcmills
Copy link
Contributor

bcmills commented Aug 3, 2020

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.

@seankhliao
Copy link
Member

I guess we can close this now the cmd/go just links to https://go.dev/ref/mod for documentation, which has a dedicated replace section https://go.dev/ref/mod#go-mod-file-replace

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
Documentation GoCommand cmd/go modules NeedsFix The path to resolution is known, but the work has not been done.
Projects
None yet
Development

No branches or pull requests

8 participants