Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

A guide to binary compatibility for library authors #621

Closed
lrytz opened this issue Nov 9, 2016 · 13 comments
Closed

A guide to binary compatibility for library authors #621

lrytz opened this issue Nov 9, 2016 · 13 comments
Labels

Comments

@lrytz
Copy link
Member

lrytz commented Nov 9, 2016

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
Copy link
Member

sjrd commented Nov 9, 2016

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
Copy link
Member

jvican commented Nov 24, 2016

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
Copy link

zjffdu commented Jul 24, 2017

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

@heathermiller
Copy link
Member

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
Copy link
Member

sjrd commented Jul 24, 2017

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
Copy link
Member

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

@jvican
Copy link
Member

jvican commented Jul 24, 2017

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

@DarkDimius
Copy link
Member

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
Copy link
Contributor

jatcwang commented Sep 4, 2017

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
Copy link
Member

@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
Copy link
Member

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

@jatcwang
Copy link
Contributor

jatcwang commented Sep 7, 2017

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

@jvican
Copy link
Member

jvican commented Jan 14, 2018

Done in #881, closing!

@jvican jvican closed this as completed Jan 14, 2018
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
Projects
None yet
Development

No branches or pull requests

8 participants