Go mod replace and github forks of /vN repositories - go

Question

I've just sent a pull request to http://periph.io/x/devices/v3; it's already been merged, but something about the process was suboptimal:
First I cloned the repository (which is actually http://github.com/periph/devices; the module is named periph.io/x/devices/v3 though), so my fork is automatically called http://github.com/lutzky/devices. I wanted to test a separate piece of code I'm working on with the modified library, call it testclient; adding this to testclient/go.mod works:
replace periph.io/x/devices/v3 v3.6.9 => ../devices
However, this should also work (and would be useful if the pull request took longer to be accepted), and doesn't:
replace periph.io/x/devices/v3 v3.6.9 => github.com/lutzky/devices main
That gives this error:
testclient/go.mod:15: replace github.com/lutzky/devices:
version "v0.0.0-20210508194004-cae0146d8900" invalid:
go.mod has post-v0 module path "periph.io/x/devices/v3" at revision cae0146d8900
On a hunch, I figured I'd create a tag v3.6.9-newfeature and push that to my fork, and point the replace command at that. That doesn't work either:
testclient/go.mod:15: replace github.com/lutzky/devices:
version "v3.6.9-newfeature" invalid:
module contains a go.mod file, so major version must be compatible: should be v0 or v1, not v3
So I can't use a v0 tag because go.mod says it's v3, but I can't use a v3 tag because the URL doesn't have /v3. I don't think I should modify go.mod in my forked repository (for one thing, that'd make the pull request silly). What's the intended way to go about this?

Answer 1

Here's the fix that you are looking for, I tested the following go.mod file and it works,
module test
go 1.14
replace periph.io/x/devices/v3 => github.com/lutzky/devices/v3 v3.6.9-newfeature
require (
periph.io/x/devices/v3 v3.6.9 // indirect
)
I first installed periph.io/x/devices/v3,
go get periph.io/x/devices/v3
Then I inserted the replace in go.mod,
replace periph.io/x/devices/v3 => github.com/lutzky/devices/v3 main
Format: replace <original_module> => <forked_repo> <branch>
Then I ran just go get. After that, the main in the replace instruction got swapped with v3.6.9-newfeature which is the latest tag on the forked repo's main branch, thus giving you the content that you see above.

Answer 2

Thanks to ramaraja-ramanujan#'s answer and a bit more debugging, I found the answer.
TL;DR - the correct answer is:
replace periph.io/x/devices/v3 v3.6.9 => github.com/lutzky/devices/v3 main
// this part was missing ^^^
This will work immediately when building, and go mod tidy (or go get) will change main to a specific tag. There are a couple of interesting side-notes to this:
The go proxy
The v3.6.9-newfeature tag was my own; I had created it as part of trying to get this to work. I've deleted it, and yet go mod tidy kept replacing main with v3.6.9-newfeature - no matter how many caches I cleared! Running strace it turned out that go was contacting http://proxy.golang.org. To disable this, I ran GOPROXY=direct go get. This replaced the line with the pseudo version v3.6.10-0.20210508194004-cae0146d8900. Note that this matches the current main commit in my fork, and neither my fork nor the original repo have v3.6.10 - it appears to have started with the existing v3.6.9 and incremented it.
The /v3 is not a subdirectory
Indeed, the source repo (https://github.com/periph/devices) does not have a v3 subdirectory. I thought what was going on is that the periph.io domain is doing some trickery - indeed going to http://periph.io/x/devices/v3 with a browser does work. However, it would appear that Go's resolution takes the final /v3 in the module path not to indicate, in this case, a subdirectory (but indeed a restriction on tag names). This is apparently allowed, and is discussed in https://golang.org/ref/mod, but it isn't entirely straightforward.