Go mod replace and github forks of /vN repositories

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.