proposal: module system: improve replace directive compatibility with forked v2 modules

[insistedMarin]

Proposal Details

Proposal: Improve Go module system's replace directive to better support forked v2 modules without requiring changes to the module path.

Problem:
When working with a forked Go module that uses a v2 or higher version, the replace directive in the main project's go.mod file does not work as expected. Specifically:

1. The original module (github.com/coming-chat/go-sui/v2) uses v2.0.1 as its version, with the module path specified as module github.com/coming-chat/go-sui/v2 in go.mod.
2. I created a fork (github.com/example/go-sui-sdk) and kept the module path in the forked go.mod the same as the original (module github.com/coming-chat/go-sui/v2) to avoid changing import paths in dependent projects.

However, I encountered two issues when trying to use this fork with the replace directive:

• Without a version tag: If I do not tag my fork with v2.0.1, Go fails to find the module when I attempt to replace it and import it in my main project.
• With a v2.0.1 tag: When I tag the fork with v2.0.1, I get the error replace github.com/example/go-sui-sdk: version "v2.0.1" invalid: should be v0 or v1, not v2, because Go expects the path of the fork to include /v2 in the repository URL to match the v2 version.

This creates a dilemma:

• If I change the module path in my fork to include /v2, it breaks compatibility with existing import paths in code that depends on the original module.
• If I keep the module path the same, I am unable to use a v2 version tag in the replace directive.

Proposed Solution:
Allow the replace directive to work with forked modules that retain the original module path, even if they use a v2 or higher version. This could involve:

• Allowing replace to recognize tags like v2.0.1 on forks without requiring the /v2 suffix in the repository path.
• Providing better documentation or guidelines for handling forks of v2 modules.

Steps to Reproduce:

1. Fork github.com/coming-chat/go-sui/v2 and keep the module path in the fork's go.mod file as module github.com/coming-chat/go-sui/v2.
2. Tag the fork with v2.0.1.
3. In the main project, add replace github.com/coming-chat/go-sui/v2 => github.com/example/go-sui-sdk v2.0.1 in go.mod.
4. Run go mod tidy and observe the error: replace github.com/example/go-sui-sdk: version "v2.0.1" invalid: should be v0 or v1, not v2.

Additional Information:

• Go Version: go1.18
• Operating System: macOS
• Workarounds Attempted:
  • Using a local path replacement: Works for development but is not ideal for production deployment.
  • Using a commit hash instead of a version tag: Still faces compatibility issues with Go mod’s versioning rules.

This enhancement would improve the flexibility of the Go module system, making it easier for developers to work with forked v2 modules without modifying import paths or module paths.

[gabyhelp]

Related Issues

• cmd/go: Replace a v2 mod where there isn't a v2 directory #49444 (closed)
• cmd/go: allow replacement modules to alias other active modules #26904
• proposal: cmd/go: permit replace in go.mod to act as path alias #35382 (closed)
• cmd/go: document that filesystem-based replace directives require that the right hand side have a go.mod #30847
• affected/package: cmd/go allow renaming a module without replacing all import paths #59766 (closed)
• proposal: cmd/go: `go get` automatically add `replace` in go.mod #39185

Related Code Changes

• cmd/go: use replacement, not replaced, module paths in binary
• cmd/go: improve handling of gopkg.in modules

Related Documentation

• Go Wiki: Go Modules > FAQs — Additional Control > When should I use the replace directive?
• go.mod file reference > replace > Examples

_{(Emoji vote if this was helpful or unhelpful; more detailed feedback welcome in this discussion.)}

[insistedMarin]

I've resolved the issue. The root cause was that the original project didn't follow Go's versioning convention for v2 modules. Specifically, Go expects that v2 (and higher) versions should have a /v2 suffix in both the module path and the directory structure.

To fix this in my fork, I created a v2 subdirectory and moved all files there. I also updated the go.mod file within the v2 directory to include /v2 in the module path. After creating a new v2.0.1 tag, the replace directive now works as expected, and Go recognizes the module correctly as a v2 version.

[seankhliao]

The directive should have been

replace github.com/coming-chat/go-sui/v2 => github.com/example/go-sui-sdk/v2 v2.0.1