A Go build links both example.com/lib and example.com/lib/v2 — why do their types refuse to interoperate?

## Why the compiler says no Go's type identity rule is simple and absolute: a **defined type** is identified by its name *and* the package that defines it, and a package is identified by its import path. `example.com/lib` and `example.com/lib/v2` are different import paths, so `lib.Client` and `v2.Client` are different types, no matter how identical their fields are. Assigning one to the other, or passing one to a function expecting the other, does not compile — and the message names both types by their full paths, which is exactly how you tell this apart from an ordinary typo. Seeing two paths that differ only by a `/v2` in a single error is the diagnosis. This is not a defect of module versioning; it is the same rule that stops you passing a `mypkg.ID` where an `otherpkg.ID` is expected. Semantic import versioning simply makes the two packages *look* like the same package to a human reader. ## What actually bites in production The assignment error is the friendly case, because it is a compile failure with a clear message. The problems that survive compilation are the ones that cost a night: **Duplicated package-level state.** Each major is its own package, so each has its own package-level variables and its own `init` functions. A registry that drivers or plugins register into now exists twice, and a plugin that registered with v1 is invisible to a lookup through v2. A package-level default client, a cached configuration, a `sync.Once` guarding one-time setup — all doubled. This is the single most common way two-major coexistence goes wrong, and it produces "it works locally, it is empty in production" behaviour rather than a build error. **Sentinel errors and error matching.** `errors.Is(err, lib.ErrNotFound)` returns false for an error produced by the v2 package, because v2 has its own distinct `ErrNotFound` value. Error handling code written against v1 silently stops recognising failures once part of the system moves. The same holds for `errors.As` with a v1 concrete error type: a v2 error will never match it. **Interfaces do not bridge automatically either.** An interface type declared in v1 is a different type from the identically-shaped one in v2, though a concrete type satisfies both if its method signatures mention no version-specific types. The moment a method takes or returns `lib.Options`, the two interfaces genuinely diverge and no value satisfies both. **Binary size and initialisation cost.** Both trees are compiled in, both sets of `init` functions run, and any expensive package-level setup happens twice. ## Can you convert between them? Sometimes, and it is a trap worth naming. Two defined types with *identical underlying types* can be converted explicitly, so `v2.Config(oldCfg)` may compile when the structs happen to match field for field. That is fragile: it silently stops compiling the moment either major changes a field, and it does nothing for interfaces, methods or errors. Treat an explicit conversion as a short-lived shim, not a strategy. ## How to run the migration so this does not hurt 1. **Choose a seam where no value crosses.** Migrate whole packages, not individual call sites, and pick boundaries where the interface between the migrated and unmigrated code is your own types rather than the library's. A background job, a single handler, or one storage adapter is usually a clean unit. 2. **Write the adapter deliberately if a value must cross.** One small package that converts v1 types to v2 types in one direction, owned and tested, beats conversions scattered through the codebase. Give it a deletion date. 3. **Watch for shared global state before you start.** If the library registers drivers, keeps a package-level default, or reads process-wide configuration in `init`, coexistence is much riskier than the type errors suggest — that state will exist twice with no warning. In that case migrate in one change rather than gradually. 4. **As the library author, consider making one major a wrapper.** If v1 is reimplemented as a thin shim over v2, then even a program requiring both paths links one implementation and one set of globals. It costs the author a release and saves every consumer the hard part. 5. **Finish.** Two majors in a build should be a state you pass through, not one you live in. Track the remaining v1 imports as work, because every day both are present is a day the seam can grow. ## What a strong answer sounds like Name the rule (type identity includes the import path), name the surprise (duplicated package-level state and sentinel errors, which compile fine), and describe a migration seam. Saying "you cannot have two majors in one build" is wrong and gives away that you have never done the migration — the whole point of the `/vN` path is that you can.