After a whole day of reading and researching, I'm still baffled by some of the features. In particular, I find problematic the combination of these two pieces of docs:

1 About semantic import versioning: https://github.com/golang/go/wiki/Modules#semantic-import-versioning

2 Releasing a v2+ module: https://github.com/golang/go/wiki/Modules#releasing-modules-v2-or-higher

Basically they turned a piece of advice into a requirement. I'm talking about the import compatibility rule, summarized by this statement: "If an old package and a new package have the same import path, the new package must be backwards compatible with the old package."

This mostly results in having to maintain either separate branches, or even same-branch separate sub-directories containing the major version code. Example: https://github.com/nicksnyder/go-i18n

The main issue I have with this advice becoming a requirement is that VCS's (VERSION control systems) inherently manage versions. I can prevent you from downloading a backwards-incompatible version of my code just with tags and semver.

I understand that import versioning might help solve the problem of diamond imports, but I don't see why the solution must be a toolchain-level VCS that overlaps with my repository VCS.

I must be missing some major point here. I would love to hear HN's opinion on this.