A guide to binary compatibility for library authors

[lrytz]

It would be great to have a guide about binary compatibility for library authors: what is a good policy to follow for your libraries, how to use version numbers, how to check binary compatibility using MiMa, details on what kind of changes are / aren't binary compatible.

[sjrd]

I've wanted to write such a guide for quite some time, now. But as with all things, time is lacking. I'd be happy to point a few ideas to someone motivated, though, as well as review such a guide.

[jvican]

I think this is a fantastic idea and everyone in the ecosystem would benefit from it. I would extend it to source compatibility also. Despite not having a tool to check it, it'd be good to give developers some rule of thumbs and guidelines.

[zjffdu]

Any update on this ? I also need some guidance on binary compatibility. Thanks

[heathermiller]

So far, no one has stepped up to do this.

All we have at the moment is a document which discusses binary compatibility of Scala releases. Not yet something specifically aimed at authors of libraries.

However, maybe info from this guide is useful for general library authors? @sjrd @lrytz could you add a few sentences explaining what you had in mind for a document aimed specifically at library authors?

[sjrd]

There's a bunch of stuff to say about the topic.

• Explain why binary compatibility is an issue for library authors. Basically explain the diamond problem (in the dependency graph) and dependency hell when libraries evolve in binary incompatible ways.
• Talk about how language features impact binary compatibility: fields in traits, case classes, default parameters, type inference of result types, etc.
• Understand how to use MiMa, and how to interpret its output. Be able to diagnose whether its error messages can be safely filtered out or not.
• Give strategies on how to define public APIs so that they can be later evolved in source and binary compatible ways: avoid default parameters (prefer overloads), avoid case classes unless they are really meant for pattern matching (in which case they're frozen forever), seal/finalize everything possible, especially traits, use abstract classes instead of traits if new fields are expected in the future, etc.
• Give some tricks that can help maintain binary compatibility when things were not planned carefully enough, as a last resort.

There's a lot to say about this.

[heathermiller]

Thanks for the list, Séb. It's really helpful for someone to potentially use as a starting point.

[jvican]

I may step up to do this if someone does not beat me to it.

[DarkDimius]

There is also a SIP in works that would check that class does not use language features that may not be binary compatible across major Scala versions : http://docs.scala-lang.org/sips/pending/binary-compatibility.html

But I've currently put it on hold due to lack on time.

[jatcwang]

Hi I'm happy to help write this guide and to learn a thing or two myself along the way :)

I'm assuming that this will be under Guides. I think the content quite a bit with Binary Compatibility of Scala Releases, should I try to merge them?

[heathermiller]

@jatcwang Perhaps a good place to discuss with @DarkDimius and @jvican about how to organize the effort around writing such a guide is the scala/contributors gitter channel? (Just trying to get this discussion started)

[SethTisue]

it should say not to use the inliner, see e.g. scala/bug#10489

[jatcwang]

That's a good example, thanks Seth. I'll jump on the channel to discuss my current draft.