1

This is specific for: https://github.com/twitchtv/twirp

This library is currently on version v7, and we would like to migrate it into go modules. The library is currently imported from other libraries like this:

// go.mod
require github.com/twitchtv/twirp v7.2.0+incompatible

// .go code
import "github.com/twitchtv/twirp"

If we add a go.mod file in the library, now every other library is forced to change the import paths like this:

// go.mod
require github.com/twitchtv/twirp v7.2.0

// .go code
import "github.com/twitchtv/twirp/v7"

How can we migrate the Twirp library to use go modules without forcing other libraries to update their import path?

The main issue here is that a single service may import multiple Twirp clients that were generated on different versions, and make use of helper functions that depend on specific types. Forcing the import path update would force all those helper functions to require managing both the old and new types, and we can't make aliases for all types (some types are functions). This would create an upgrade lock. Does this mean that the Twirp library needs to stay in +incompatible mode forever?

tothemario
  • 5,851
  • 3
  • 44
  • 39

1 Answers1

3

How can we migrate the Twirp library to use go modules without forcing other libraries to update their import path?

You can't.

If your go.mod declares the module as github.com/twitchtv/twirp/v7, then every client library (and your own packages) will have to update the import path. That's just how semantic import paths were intended to work in Go modules.

If you use v1 or v0 module path — which is written without the suffix — you are breaking the semver contract, since your project actually has already v7 tags.

The main issue here is that a single service may import multiple Twirp clients that were generated on different versions

Migrating to Go modules explicitly solves this in a clean way, i.e. clients that import multiple versions of your project just declare imports as github.com/twitchtv/twirp/vX etc, making it immediately apparent also in .go files what versions they are using.

Actually you have a very easy way to deal with this. Just migrate to Go modules declaring your module as with the next major version suffix github.com/twitchtv/twirp/v8, then tag it v8.x.y. This is correct from a semver perspective, since your change is indeed breaking — your clients must change the import paths.

This way, clients that do want to migrate to your Go modules version will know what to expect and deal with the implications of switching to a new major version, including rewriting the import paths. Whereas clients that do not want to migrate can keep importing a v7.x.y (or less) as +incompatible.

blackgreen
  • 34,072
  • 23
  • 111
  • 129
  • The issue is not with the clients that require twirp in different versions, but with the helper functions that handle types like `twirp.Error` from multiple clients. It's the 3rd level dependencies that will block the upgrades. It doesn't matter if clients update to the new version and change their import path, nothing is going to be updated until all services that require those clients update all their helper functions to handle both `twirp.Error` (for old clients) and `twirpv8.Error` (for new clients) at the same time. Seems like a big hassle. – tothemario Apr 16 '21 at 04:53
  • @tothemario I understand, I think the recommendation to upgrade to v8 still applies. As long as you signal the major change with semver, all those who provide helper functions will either upgrade a major themselves or add new handlers for v8 types. And those importing both `twirp` and third-party helper packages will upgrade their deps accordingly. But this is out of your control. What you can do is to provide proper semver-compliant upgrades and documentation about how to migrate. Doing version or import path trickery is worse. – blackgreen Apr 16 '21 at 07:59
  • Is there a specific reason you can't define `twirp.Error` in versions prior to `v8` as aliases for `twirpv8.Error`? You say “we can't make aliases for all types (some types are functions)”, but type aliases *can* refer to function types, and function types that are identical modulo aliases are equal (https://play.golang.org/p/7Q8yLOXiKS6). – bcmills Jun 29 '21 at 03:01