API compatibility - transitive major version increment

[roger peppe]

We use gopkg.in quite a bit and it's been working well
for us. I'd like raise an issue that we've encountered
recently and ask for reactions.

Say I have a package gopkg.in/a.v1:

package a
import "gopkg.in/b.v4"
func Foo() b.Bar

and I change it to use gopkg.in/b.v5, do I need to
bump gopkg.in/a.v1 to v2 ?

More succinctly, if a dependency's major
version changes and it appears in the public
API, does that count as a major API version change?

I suspect the answer is "yes" (by the gopkg.in compatibility
rules, the types have changed) but I don't particularly
like it as it means that a package version must increment
if *any* of the dependencies mentioned in its public API
change version.

What do you think?

cheers,
rog.

[alexandr...@gmail.com]

I think the version number should be bumped if b.v5.Bar is not backward compatible with b.v4.Bar.

And as a rule of thumb a package should avoid exposing other packages' types.

[Chris Hines]

On Thursday, April 23, 2015 at 9:02:20 AM UTC-4, rog wrote:

We use gopkg.in quite a bit and it's been working well
for us. I'd like raise an issue that we've encountered
recently and ask for reactions.

Say I have a package gopkg.in/a.v1:

    package a
    import "gopkg.in/b.v4"
    func Foo() b.Bar

and I change it to use gopkg.in/b.v5, do I need to
bump gopkg.in/a.v1 to v2 ?

More succinctly, if a dependency's major
version changes and it appears in the public
API, does that count as a major API version change?

Yes, but only because it appears in the public API of package a. If the dependency is only used internally and package a's public API has not changed, then package a can stay at v1. It's all about the public API.

 

I suspect the answer is "yes" (by the gopkg.in compatibility
rules, the types have changed) but I don't particularly
like it as it means that a package version must increment
if *any* of the dependencies mentioned in its public API
change version. 

 

What do you think?

  cheers,
    rog.

Yes, it is annoying, but it also puts more pressure on package authors to think about API compatibility. Hopefully that outweighs the cost over the long term.

We had a brief conversation about a related question at https://github.com/inconshreveable/log15/issues/53.

My initial concern that started the discussion was:

... it is mildly annoying that one must import log15.v2 in order to implement a Handler (because of the *log15.Record argument). So Handlers are always coupled to log15.v2. This may cause problems down the road for people that implement custom handlers in a library. Consumers of such Handlers will have a harder time upgrading to a putative log15.v3 because I'm pretty sure that all the Handlers in an application must have the same import path for *Record. I'm not sure what to do about that yet.

This situation acts as a drag on adoption of newer versions, or, for the API developer, acts as a drag on introducing breaking changes. But that could be a good thing, depending on your point of view.

Chris 

 

[Dan Kortschak]

Or if the imported package interacts with resources that are managed tightly by that package - if you don't bump the version an importer may now have two versions of the package a imports that are competing for the resource because they now don't communicate.