Guide on binary compatibility for library authors #881

jatcwang · 2017-09-11T12:28:15Z

Added guide on binary compatibility, with library authors as the target audience. Addresses #621

After building you can see the guide on http://localhost:4000/tutorials/binary-compatibility-for-library-authors.html

TODOs:

Able to navigate to the actual guide from the homepage
"Designing for Evolution" section - I'm setting up an example repo to present this information with more detail (and actual code examples that show the breakages). Will link it in the main guide after I'm happy with it DONE

Let me know if there are things that I've missed. I'm also up for reorganization if you think it will help with the presentation/delivery.

ktoso · 2017-09-12T09:03:39Z

_overviews/tutorials/binary-compatibility-for-library-authors.md

+* Any release with the same major version are **Binary Backwards Compatible** with each other
+* A minor version bump signals new features and **may contain minor source incompatibilities** that can be easily fixed by the end user
+* Patch version for bugfixes and minor behavioural changes
+* For **expreimental library versions** (where the major version is `0`, such as `v0.1.0`), a minor version bump **may contain both source and binary breakages**


typo, experimental

DaniRey · 2017-09-12T11:48:25Z

_overviews/tutorials/binary-compatibility-for-library-authors.md

+if we say that any library release of `v1.x.x` will be forwards compatible, we can use `v1.0.0` anywhere where `v1.1.0` was originally used.
+For the rest of the guide, when the 'compatible' is used we mean backwards compatible, as it is the more common case of compatibility guarantee.
+
+An important note to make is that while breaking source compatibility normally results in breaking binary compatibility, they are actually orthorgonal 


Typo: orthogonal

DaniRey · 2017-09-12T11:51:33Z

_overviews/tutorials/binary-compatibility-for-library-authors.md

+
+![Initial dependency graph]({{ site.baseurl }}/resources/images/library-author-guide/before_update.png){: style="width: 280px; margin: auto; display: block;"}
+
+Some time later, we see `B v1.1.0` is now available and we upgraded the version in our `build.sbt`. Our code compiles and seems to work so we push it to production and goes home for dinner.


Times and Typo:
Some time later, we see B v1.1.0 is available and upgrade its version in our build.sbt. Our code compiles and seems to work so we push it to production and go home for dinner.

DaniRey · 2017-09-12T11:52:51Z

_overviews/tutorials/binary-compatibility-for-library-authors.md

+
+Now imagine if our App is more complex with lots of dependencies themselves depending on `C` (either directly or transitively) - it becomes extremely difficult to upgrade any dependencies because it now
+pulls in a version of `C` that is incompatible with the rest of the versions of `C` in our dependency tree! In the example below, we cannot upgrade `D` because it will transitively pull in `C v2.0.0`, causing breakages
+due to binary incompatibility. This inability to upgrade any packages without breaking anything is common known as **Dependency Hell**.


Typo: commonly

DaniRey · 2017-09-12T11:55:05Z

_overviews/tutorials/binary-compatibility-for-library-authors.md

+and all other versions of the same library are **evicted**. When packaging applications, the same versions of libraries that was used for compiling the 
+application is packaged and used during runtime.
+
+Two library versions are said to be **Source Compatible** if switching one for the other does not incur any compile errors. For example, If we can switch from `v1.0.0` of a dependency to `v2.0.0` and


I would prefer if the examples would use the proposed versioning scheme. I think it's easier for the reader to follow and internalize it's rules.

Yeap good catch. That's my intention too.

jvican

Hey @jatcwang, really cool work. I propose some rewordings and slight modifications to improve the correctness and readability of the document.

I'm really excited that you took up this task, and I'd like to thank you personally for taking the time to write this down.

jvican · 2017-09-12T12:17:10Z

_overviews/tutorials/binary-compatibility-for-library-authors.md

+## Introduction
+
+A diverse and comprehensive set of libraries is important to any productive software ecosystem. While it is easy to develop and distribute Scala libraries, good library authorship goes far
+beyond just writing code and publishing them.


I'd write "beyond just writing code and publish it".

jvican · 2017-09-12T12:18:28Z

_overviews/tutorials/binary-compatibility-for-library-authors.md

+In this guide, we will cover the important topic of **Binary Compatibility**:
+
+* How binary incompatibility can cause production failures in your applications
+* How library authors can avoid breaking binary compatibility, and/or convey breakages clearly to library users when they happen


I would split this last item in two:

How library authors can avoid breakages in binary compatibility

How to reason about the impact of binary incompatible changes

Are there different levels of "impact` for binary incompatibility?

Not really. In hindsight, that last bullet point doesn't explain what I wanted to. Let me reword it: "How to reason about the impact of changes in their code". And I would put it in the second position instead of the last one.

jvican · 2017-09-12T12:19:09Z

_overviews/tutorials/binary-compatibility-for-library-authors.md

+* How binary incompatibility can cause production failures in your applications
+* How library authors can avoid breaking binary compatibility, and/or convey breakages clearly to library users when they happen
+
+Before we start, first we need to understand how code is compiled and executed on the Java Virtual Machine (JVM).


~~first we need to understand~~ -> let's understand

jvican · 2017-09-12T12:21:11Z

_overviews/tutorials/binary-compatibility-for-library-authors.md

+
+## The JVM execution model
+
+Code compiled to run on the JVM is compiled to a platform-independent format called **JVM bytecode** and stored in **Class File** format (with `.class` extension) and these class files are stored


~~Code compiled to run on the JVM~~ -> Scala
~~stored in Class File format~~ -> stored in .class files.

jvican · 2017-09-12T12:22:32Z

_overviews/tutorials/binary-compatibility-for-library-authors.md

+Code compiled to run on the JVM is compiled to a platform-independent format called **JVM bytecode** and stored in **Class File** format (with `.class` extension) and these class files are stored
+in JAR files. The bytecode is what we refer to as the **Binary** format.
+
+When application or library code is compiled, their bytecode invokes named references of classes/methods from their dependencies instead of including the dependencies' actual bytecode


I prefer "When an application depends on a library, its compiled bytecode references to the library's bytecode"

That's better. One important point I want deliver is that application code is calling the "bytecode interface" of the library, which means modifying the internal of methods is OK and won't break bin-compat. What's the right technical term for this?

I would call it "binary interface" though I don't know the academic term. If you want to make this more obvious, I would create a new paragraph (or even better: enclose it in a -- there are some other blog posts that do it).

jvican · 2017-09-12T12:40:36Z

_overviews/tutorials/binary-compatibility-for-library-authors.md

+This situation can only be resolved by ensuring that the chosen version of `C` is binary compatible with all other evicted versions of `C`. In this case, we need a new version of `A` that depends
+on `C v2.0.0` (or any other future `C` version that is binary compatible with `C v2.0.0`).
+
+Now imagine if our App is more complex with lots of dependencies themselves depending on `C` (either directly or transitively) - it becomes extremely difficult to upgrade any dependencies because it now


I would make 'App' lowercase 😄

App is the name of our application, just like A, B are the names of the libraries. Can wrap it in inline-code it so it's more obvious.

jvican · 2017-09-12T12:41:36Z

_overviews/tutorials/binary-compatibility-for-library-authors.md

+
+## Versioning Scheme - Communicate binary compatibility breakages
+
+We recommend using the following schemes to communicate binary and source compatibility to your users:


We strongly recommend.

jvican · 2017-09-12T12:42:23Z

_overviews/tutorials/binary-compatibility-for-library-authors.md

+
+TODO
+
+## Versioning Scheme - Communicate binary compatibility breakages


What if you try to explain what a versioning scheme is and maybe quote the semantic versioning spec? I feel like a small introduction here would make the reading much much nicer for beginners.

I didn't want to mention semantic versioning at all because it brings in the wrong correlation and might confuse the reader.

MAJOR version when you make incompatible API changes,

In the versioning scheme we're recommending, major version bump has nothing to do with API changes. (From my point of view, API changes = source incompatibility)

but yeah, we can briefly explain what versioning schemes are

I didn't want to mention semantic versioning at all because it brings in the wrong correlation and might confuse the reader.

I'm not sure about this. The versioning scheme that we recommend is a more constrained subset of semantic versioning. I feel mentioning semantic versioning here is a must, it's a widely used standard. We should make it obvious that our versioning scheme enforces more information in every Scala version, which is extremely advantageous.

(From my point of view, API changes = source incompatibility)

Not really, API changes happen because of both binary and source incompatible changes.

jvican · 2017-09-12T12:57:05Z

_overviews/tutorials/binary-compatibility-for-library-authors.md

+
+We recommend using the following schemes to communicate binary and source compatibility to your users:
+
+* Any release with the same major version are **Binary Backwards Compatible** with each other


Okay, this is how I propose you write this:

Any library versioned with a starting 0 can break binary and source compatibility at any time, as of the [semantic versioning](link here) spec.

A change in the major version number signals at least one binary incompatibility, either forwards and/or backwards. For example, code compiled against v1.0.0 is not compatible with v2.0.0.

A change in the minor version number signals at least one source incompatibility, either forwards and/or backwards. For example, code compiled against the sources of a dependency v1.0.0 is not ensure to compile with v1.1.0 of the same library.

A change in the patch version (the x in 1.0.x) signals no binary or source incompatibility. Patch releases often include bug fixes and minor behavioural changes.

There may be cases in which libraries break source compatibility and decide to bump up the major version number. These cases, where not common, are defined per library.

I think the new format is much more readable and more "structured". The dumber the bullet lists are, the better ^^

One thing is not clear to me is the status we give to forward binary compatibility. We should probably say that it's often the case that libraries do not promise forward binary compatibility, and that therefore they don't influence major version numbers. I'll think about this in the next hours since now I'm saturated, but perhaps @sjrd can shed some light on this. He's the original author of this proposal.

Forward compat is generally not an issue and does not count per se in the versioning number I am advocating.

However, checking forward binary compatibility with MiMa is the best approximation we have of guaranteed (100%) backward source compat. Indeed, the most common source for backward source incompatibility are additions of public fields/methods (which influence implicit resolution), and that is forbidden if you enforce forward binary compat. Therefore, I would in general encourage checking forward bin compat across patch releases (so between 1.2.x and 1.2.y), which is the best thing we have to enforce backward source compat in patch releases.

I agree with @sjrd regarding forward compatibility not being as relevant for most userland libraries

I am still on the fence about minor versions. I know a lot of libraries like to use minor version to signal new features. Perhaps we make minor version a mandatory bump if forward compatibility is broken? (which normally coincides with adding new functionality like new methods).

Does the SBT MiMa plugin currently support easy checking for forward compatibility?

Just an idea: I think we should extend MiMa SBT plugin to automatically suggest a new version number based on the result of compatibility check. (Although I'm not sure if there's a way to check source compatibility..)

jvican · 2017-09-12T12:57:57Z

_overviews/tutorials/binary-compatibility-for-library-authors.md

+
+### Explanation
+
+Why do we use the major version number to signal binary compatibility releases?


to signal binary incompatible releases

jvican · 2017-09-12T13:04:30Z

@jatcwang I'm really not a fan of the GitHub way of reviewing this. If you prefer it, I can add all my suggestions as a commit to this PR, and then you review my commit and change the things you don't like.

I feel that would be a much faster way of reviewing it, and would save you time.

sjrd · 2017-09-12T13:14:40Z

I will not have time this week to review this, because of a paper deadline. I will get to it next week.

jatcwang · 2017-09-13T11:20:07Z

@jvican That'll be awesome thank you. I've left comments on all of your feedback but feel free to make changes as you see fit.

jatcwang · 2017-09-26T12:42:24Z

I have just uploaded a repo to demonstrate common causes of binary incompability + more detailed explanation that I can't cover in the main guide. The intention is to provide a link to this repo from the main guide.

https://github.com/jatcwang/binary-compatibility-guide

Please raise issues in that repo for anything you think I've missed.

@jvican I am happy to update my PR to address your feedback so let me know if you're struggling to find time.

jvican · 2017-09-26T13:00:59Z

I'm struggling to find time atm, but I'll review further updates on this PR.

jatcwang · 2017-10-01T13:19:38Z

Pushed some commits that hopefully addresses all your feedback @jvican. (Much appreciated - it reads better now)

heathermiller · 2017-10-03T12:54:22Z

🎉 🎉
@jvican can you have a look at this when you're back in the office?

And again, sincerest thanks for taking the initiative on this @jatcwang ❤️

heathermiller · 2017-10-03T12:55:27Z

@sjrd too, if you're interested in/have time to provide a review, I know it'd be appreciated.

jvican

Excellent work @jatcwang. I could only review until "An example of dependency hell". I'm planning to continue the review tomorrow.

Also, this commit (jvican@96b49ad) moves the guide from the tutorials section to the guides section. I think that this one is more appropriate for such a document.

jvican · 2017-10-19T20:47:23Z

_overviews/tutorials/binary-compatibility-for-library-authors.md

+for all of `App`, `A` and `C` (something like `java -cp App.jar:A.jar:C.jar:. MainClass`). If we did not provide `C.jar` or if we provided a `C.jar` that does not contain some classes/methods
+which `A` calls, we will get classloading exceptions when our code attempts to invoke the missing classes/methods.
+
+These are what we call **Binary Incompatibility Errors**. An error caused by binary incompatibility happens when the compiled bytecode references a name that cannot be resolved during runtime


You have here and in some sentences before some missing dots 😄.

I have no idea what you're talking so I just rewrote it and add the missing full stop at the end 😛

jvican · 2017-10-19T20:48:39Z

_overviews/tutorials/binary-compatibility-for-library-authors.md

+When a class is needed during execution, the JVM classloader loads the first matching class file from the classpath (any other matching class files are ignored).
+Because of this, having multiple versions of the same library in the classpath is generally undesireable:
+
+* Unnecessary application size increase


Why does the "application size" increase? This sentence is a little bit misleading. I think that what you mean here is that "build tools need to resolve and download unnecessary dependencies that take time and space".

If the build tool bundles all different version of a library with the application (however it is distributed), then you have unnecessary bloat in your bundle. Happy to reword or remove if you find it confusing

Yes, I think that it requires some clarification 😄. Also, consider adding my remark, I think it's valid.

jvican · 2017-10-19T20:48:56Z

_overviews/tutorials/binary-compatibility-for-library-authors.md

+
+## What are Evictions, Source Compatibility and Binary Compatibility?
+
+### Evictions


I like how you explain evictions, well done.

jvican · 2017-10-19T20:49:39Z

_overviews/tutorials/binary-compatibility-for-library-authors.md

+
+These are what we call **Binary Incompatibility Errors**. An error caused by binary incompatibility happens when the compiled bytecode references a name that cannot be resolved during runtime
+
+## What are Evictions, Source Compatibility and Binary Compatibility?


I think there's some disconnect between this section and the previous one. It would be good to add some paragraph connecting the two so that the user clearly sees how this one links to the previous one. This eases readability.

jvican · 2017-10-19T20:52:09Z

_overviews/tutorials/binary-compatibility-for-library-authors.md

+
+### Source Compatibility
+Two library versions are **Source Compatible** if switching one for the other does not incur any compile errors.  
+For example, If we can upgrade `v1.0.0` of a dependency to `v1.1.0` and recompile our code without any compilation errors, `v1.1.0` is source compatible with `v1.0.0`.


~~without any compilation errors~~ -> "without any compilation errors and *semantic changes at runtime". Note that if you add a new method that was previously enriched by an implicit into the base class, and that method has a different behaviour, it will compile but the application's behaviour will change.

jvican · 2017-10-19T22:06:53Z

_overviews/tutorials/binary-compatibility-for-library-authors.md

+
+## Why binary compatibility matters
+
+Binary Compatibility matters because failing to maintain it makes life hard for everyone.


What about "Breaking binary compatibility has bad consequences on the ecosystem around the software:"?

jvican · 2017-10-19T22:07:04Z

_overviews/tutorials/binary-compatibility-for-library-authors.md

+
+Binary Compatibility matters because failing to maintain it makes life hard for everyone.
+
+* End users has to update all library versions in their whole transitive dependency tree such that they are binary compatible, otherwise binary compatibility errors will happen at runtime


~~has~~ have

What about "have to update versions transitively in all their dependency tree such that they are binary compatible. This process is time-consuming and error prone, and it can change the semantics of end program."?

jvican · 2017-10-19T22:31:33Z

_overviews/tutorials/binary-compatibility-for-library-authors.md

+Binary Compatibility matters because failing to maintain it makes life hard for everyone.
+
+* End users has to update all library versions in their whole transitive dependency tree such that they are binary compatible, otherwise binary compatibility errors will happen at runtime
+* Library authors are forced to update the dependencies of their library so users can continue using them, greatly increases the effort required to maintain libraries


I think this part is not clear enough. What do you mean exactly?

reworded if that is clearer? mainly talking about users asking library authors to bump the dependency version to align the versions to be bin-compat

jvican · 2017-10-19T22:32:36Z

_overviews/tutorials/binary-compatibility-for-library-authors.md

+* End users has to update all library versions in their whole transitive dependency tree such that they are binary compatible, otherwise binary compatibility errors will happen at runtime
+* Library authors are forced to update the dependencies of their library so users can continue using them, greatly increases the effort required to maintain libraries
+
+Constant binary compatibility breakages in libraries, especially ones that are used by other libraries, is detrimental to our ecosystem as they require a lot of effort


"as they require time and effort from end users and maintainers of dependent libraries"

jvican · 2017-10-19T22:32:58Z

_overviews/tutorials/binary-compatibility-for-library-authors.md

+
+Some time later, we see `B v1.1.0` is available and upgrade its version in our build. Our code compiles and seems to work so we push it to production and go home for dinner.
+
+Unfortunately at 2am, we got frantic calls from customers saying that our application is broken! Looking at the logs, you find lots of `NoSuchMethodError` is being thrown by some code in `A`! 


isare being thrown

jatcwang · 2017-10-21T13:22:12Z

Updated according to @jvican's second round of review (thanks!) + grammar check.

heathermiller · 2017-10-27T16:44:01Z

@jvican... Can you please have a look at the rest?

heathermiller · 2017-10-27T16:44:59Z

(PS, thanks very much @jatcwang for your patience on this! And thank you for the fixes!)

jvican

@jatcwang Awesome. This is my last pass through the document. I've left some nice comments that I think can help improve the document even more. Though being honest, I think you've done a real good job at this difficult topic.

From now on, I defer my reviewing duties to someone with more expertise than I do. Once my comments are addressed, I'm happy for this to be merged! But I'd like someone else to have a look and confirm I haven't missed anything.

jvican · 2017-10-29T22:52:35Z

_overviews/tutorials/binary-compatibility-for-library-authors.md

+
+### Source Compatibility
+Two library versions are **Source Compatible** if switching one for the other does not incur any compile errors or unintended behavioral changes at runtime.  
+For example, If we can upgrade `v1.0.0` of a dependency to `v1.1.0` and recompile our code without any compilation errors, `v1.1.0` is source compatible with `v1.0.0`.


You forgot to mention here "semantic errors" too 😄

jvican · 2017-10-29T22:56:07Z

_overviews/tutorials/binary-compatibility-for-library-authors.md

+
+### Binary Compatibility
+Two library versions are **Binary Compatible** if the compiled bytecode of these versions can be interchanged without causing binary compatibility errors.  
+For example, if we can replace the class files of a library's `v1.0.0` with the class files of `v1.1.0` without any binary compatibility errors during runtime,


This is an example of backward bincompat. Since you haven't introduced here yet the two kinds of bincompat that there are, I think it's better to remove this example from here and keep the definition alone (you already have a really good diagram that exemplifies both later on, so I find it somewhat unnecessary). Then, I would remove the note at the end, and create a new section ### Relationship between binary compatibility and source compatibility where you explain in a more principled way how they interact.

jvican · 2017-10-29T22:57:03Z

_overviews/tutorials/binary-compatibility-for-library-authors.md

+
+## Why binary compatibility matters
+
+Binary Compatibility matters because breaking binary compatibility have bad consequences on the ecosystem around the software.


typo: has 😄

jvican · 2017-10-29T23:00:17Z

_overviews/tutorials/binary-compatibility-for-library-authors.md

+## MiMa - Checking binary compatibility against previous library versions 
+
+The [Migration Manager for Scala](https://github.com/typesafehub/migration-manager) (MiMa) is a tool for diagnosing binary incompatibilities between different library versions.  
+It works by comparing the class files of two provided JARs and report any binary incompatibilities found.


I would try to make more explicit that it support forwards and backwards bincompat detection with something like this: "It can tell a library author whether a change causes any kind of binary compatibility in both directions: forwards and backwards."

jvican · 2017-10-29T23:04:24Z

_overviews/tutorials/binary-compatibility-for-library-authors.md

+you have accidentally introduced binary incompatible changes. Detailed instruction on how to use the SBT plugin can be found in the link.
+
+We strongly encourage every library author to incorporate MiMa into their library release workflow.
+


Someone at some point mentioned that MiMa can be used as the best approximation of source (in)compatibility detection. I think it was a comment in this very same PR.

It may be interesting mentioning that here and also explaining that detecting source incompatibility automatically in Scala is extremely difficult because of complex scoping and certain language features like implicits, named parameters, etc.

I probably said that.

Basically, checking both forward and backward bincompat with MiMa is the closest tool we've got to checking backward source compatibility. Because it prevents, for example, from adding public methods, which is one of those things that can break source compat.

jvican · 2017-10-29T23:19:56Z

_overviews/tutorials/binary-compatibility-for-library-authors.md

+
+* Ensure major versions of all versions of a library in the dependency tree are the same
+* Pick the latest version and evict the rest (This is the default behavior of SBT).
+


In my opinion, this is one of the most important parts of the document and we need to make a good case to synthesize all the advantages to use this scheme over others. To me, the biggest advantage to users is determinism: the consequences of upgrading/downgrading a library in their projects are clearer. They can reason better about the changes produced in every release. They express the rich kind of incompatibilities in Scala.

Do you think that adding these instead of the ones you mention is better?

I see you do a similar reasoning in "Explanation". I think it may be worth considering merging this with the "Conclusion" section instead of putting it here. Do you agree?

jvican · 2017-10-29T23:22:00Z

_overviews/tutorials/binary-compatibility-for-library-authors.md

+
+From our [example](#why-binary-compatibility-matters) above, we have learned two important lessons:
+
+* Binary incompatibility releases often leads to dependency hell, rendering your users unable to update any of their libraries without breaking their application


Not only binary. I would say: "API incompatibilities often lead to dependency hell".

No, this is not accurate. That's the whole point of having bin compat in MAJOR and source compat in MINOR. Source incompatibility does NOT result in dependency hell. Only binary incompat does.

I think I explained that at length, and pretty well, in the Contributors forum at some point.

Correct, I don't know why I said otherwise in the beginning.

jvican · 2017-10-29T23:22:30Z

_overviews/tutorials/binary-compatibility-for-library-authors.md

+From our [example](#why-binary-compatibility-matters) above, we have learned two important lessons:
+
+* Binary incompatibility releases often leads to dependency hell, rendering your users unable to update any of their libraries without breaking their application
+* If a new library version is binary compatible but source incompatible, the user can simply fix the compile errors in their application and everything will work


s/everything will work/their application should work/g

jvican · 2017-10-29T23:23:28Z

_overviews/tutorials/binary-compatibility-for-library-authors.md

+* Binary incompatibility releases often leads to dependency hell, rendering your users unable to update any of their libraries without breaking their application
+* If a new library version is binary compatible but source incompatible, the user can simply fix the compile errors in their application and everything will work
+
+Therefore, **binary incompatible releases should be avoided if possible** and be more noticeable when they happen, warranting the use of the major version number. While source compatibility


~~be more noticeable~~ be "properly documented"

jvican · 2017-10-29T23:25:42Z

_overviews/tutorials/binary-compatibility-for-library-authors.md

+* If a new library version is binary compatible but source incompatible, the user can simply fix the compile errors in their application and everything will work
+
+Therefore, **binary incompatible releases should be avoided if possible** and be more noticeable when they happen, warranting the use of the major version number. While source compatibility
+is also important, if they are minor breakages that do not require effort to fix, then it is best to let the major number signal just binary compatibility.


~~if they are minor breakages that do not require effort to fix~~

The previous statement is true no matter whether that condition is true or not. The scheme signals the most severe API change, in this case breaking binary compatibility, and users should be prepared for source incompatible changes too.

I'm just gonna take out this sentence. I feel like I'm overexplaining at various places when the reader can simply figure it out later on their own

sjrd · 2017-10-30T09:23:18Z

_overviews/tutorials/binary-compatibility-for-library-authors.md

+for all of `App`, `A` and `C` (something like `java -cp App.jar:A.jar:C.jar:. MainClass`). If we did not provide `C.jar` or if we provided a `C.jar` that does not contain some classes/methods
+which `A` calls, we will get classloading exceptions when our code attempts to invoke the missing classes/methods.
+
+These are what we call **Binary Incompatibility Errors** -- errors that happen when the compiled bytecode references a name that cannot be resolved during runtime.


The technical term for the JVM is Linkage error (as evidenced by the fact that they are all subclasses of LinkageError). Linkage errors are caused by binary incompatible changes in APIs, or binary incompatibilities for short. There is no such thing as a "binary incompatibility error".

sjrd · 2017-10-30T09:29:11Z

_overviews/tutorials/binary-compatibility-for-library-authors.md

+These are what we call **Binary Incompatibility Errors** -- errors that happen when the compiled bytecode references a name that cannot be resolved during runtime.
+
+Before we look at how to avoid binary incompatibility errors, let us first
+establish some key terminologies we will be using for the rest of the guide.


There should be a short subsection about the model of other platforms (Scala.js and Scala Native). Here is a draft:

Linking model of Scala.js and Scala Native

Similarly to the JVM, Scala.js and Scala Native have their respective equivalents of .class files, namely .sjsir files and .nir files. Similarly to .class files, they are distributed in .jars, and linked together at the end.

However, contrary to the JVM, Scala.js and Scala Native link their respective IR files at link time, so eagerly, instead of lazily at run-time. Failure to correctly link the entire program results in linking errors reported while trying to invoke fastOptJS/fullOptJS or nativeLink.

Besides that difference in the timing of linkage errors, the models are extremely similar. Unless otherwise noted, the contents of this guide apply equally to the JVM, Scala.js and Scala Native.

sjrd · 2017-10-30T10:24:30Z

_overviews/tutorials/binary-compatibility-for-library-authors.md

+
+### Evictions
+When a class is needed during execution, the JVM classloader loads the first matching class file from the classpath (any other matching class files are ignored).
+Because of this, having multiple versions of the same library in the classpath is generally undesirable:


This mixes up different things. Consider replacing that paragraph with something more obviously accurate, such as

Unless using special tools such as OSGI), only one version of any given library can be loaded in the same JVM. If several are provided on the classpath, the contents of the first one will shadow the later ones.

What's inaccurate about the paragraph? I want to minimize the amount of keywords mentioned especially when they doesn't help the key message of the guide (e.g. OSGI).

I don't think "only one version of any given library" is accurate. If I have A_v1.jar and A_v2.jar in my classpath and A_v2.jar contains a class that doesn't exist in A_v1.jar, then JVM will find find and use the class in A_v2.jar no? (Your second sentence kinda hints that, but I want to be clear about it)

@jatcwang I think Sébastien's suggestion here makes sense, just make sure you add a paragraph for "(such as OSGi)" so that it has less importance. But the wording is superior in precision 😄.

sjrd · 2017-10-30T10:25:26Z

_overviews/tutorials/binary-compatibility-for-library-authors.md

+Therefore, when resolving JARs to use for compilation and packaging, most build tools will pick only one version of each library and **evict** the rest.
+
+### Source Compatibility
+Two library versions are **Source Compatible** if switching one for the other does not incur any compile errors or unintended behavioral changes at runtime.  


source compatible with each other

sjrd · 2017-10-30T10:25:41Z

_overviews/tutorials/binary-compatibility-for-library-authors.md

+For example, If we can upgrade `v1.0.0` of a dependency to `v1.1.0` and recompile our code without any compilation errors, `v1.1.0` is source compatible with `v1.0.0`.
+
+### Binary Compatibility
+Two library versions are **Binary Compatible** if the compiled bytecode of these versions can be interchanged without causing binary compatibility errors.  


binary compatible with each other

sjrd · 2017-10-30T10:46:42Z

_overviews/tutorials/binary-compatibility-for-library-authors.md

+
+### Recommended Versioning Scheme
+
+* If backward **binary compatibility** is broken, **major version number** must be increased


In English typography, there are no hard rules on the proper use of bulleted lists.

The only well-accepted rule I have seen is that, if the full list can read as a full sentence, you can write the list as if bullets were basically not semantically relevant. Therefore, the rest of the punctuation and capitalization should be applied as if they were all part of the same sentence. This means that a bullet list should look as follows:

items should not start with a capital letter,

they should all end with a comma, and

the next-to-last item ends with ", and" while the last one ends with a period.

Indeed, you can remove the bullets from the above list, and it still reads as a correct sentence.

sjrd · 2017-10-30T10:49:05Z

_overviews/tutorials/binary-compatibility-for-library-authors.md

+
+* If backward **binary compatibility** is broken, **major version number** must be increased
+* If backward **source compatibility** is broken, **minor version number** must be increased
+* A change in **patch version number** signals **no binary nor source incompatibility**. According to SemVer, patch versions should contain only bug fixes that fix incorrect behavior so major behavioral


Depending on how serious you are about source compatibility, a backward source compatible release must have exactly the same public/protected API as the previous version. It cannot even add methods. Given that SemVer itself recommends that adding functionality should bump MINOR, it's pretty clear to me that adding a public method should bump MINOR anyway.

sjrd · 2017-10-30T10:52:27Z

_overviews/tutorials/binary-compatibility-for-library-authors.md

+* A change in **patch version number** signals **no binary nor source incompatibility**. According to SemVer, patch versions should contain only bug fixes that fix incorrect behavior so major behavioral
+change in method/classes should result in a minor version bump.
+* When major version is `0`, a minor version bump **may contain both source and binary breakages**
+* Some libraries may take a harder stance on maintaining source compatibility, bumping the major version number for ANY source incompatibility even if they are binary compatible


Bumping the major version for ANY source incompatibility is probably nonsense. If you really mean ANY (and I guess you mean it, because it's uppercase), then adding a public method means you need to bump MAJOR. I don't any library will ever be that strict.

Actually, I would argue that a library doing this is doing a disservice to its community, as it has no means to effectively convey binary incompatible changes anymore in a way that is independent from source incompatible changes. This means that every single new public method breaks the ecosystem, since I cannot know from the version number whether I am moving into dependency hell or not.

sjrd · 2017-10-30T10:53:38Z

_overviews/tutorials/binary-compatibility-for-library-authors.md

+* A change in **patch version number** signals **no binary nor source incompatibility**. According to SemVer, patch versions should contain only bug fixes that fix incorrect behavior so major behavioral
+change in method/classes should result in a minor version bump.
+* When major version is `0`, a minor version bump **may contain both source and binary breakages**
+* Some libraries may take a harder stance on maintaining source compatibility, bumping the major version number for ANY source incompatibility even if they are binary compatible


MAJOR could be bumped for "severe" source breaking changes (for some definition of "severe"). Removing public APIs could be considered "severe", for example. But we cannot give any objective metric about this.

sjrd · 2017-10-30T10:56:13Z

_overviews/tutorials/binary-compatibility-for-library-authors.md

+
+From our [example](#why-binary-compatibility-matters) above, we have learned two important lessons:
+
+* Binary incompatibility releases often leads to dependency hell, rendering your users unable to update any of their libraries without breaking their application


No, this is not accurate. That's the whole point of having bin compat in MAJOR and source compat in MINOR. Source incompatibility does NOT result in dependency hell. Only binary incompat does.

I think I explained that at length, and pretty well, in the Contributors forum at some point.

jatcwang · 2017-11-12T02:09:54Z

Changes pushed. I addressed everything apart from @sjrd's comment about JVM classloading and bullet points 😛

jvican · 2017-12-07T14:24:54Z

@jatcwang Thanks ❤️.

Can you check if the document is in good shape now? @sjrd

gmethvin · 2017-12-20T10:21:41Z

_overviews/tutorials/binary-compatibility-for-library-authors.md

+
+## MiMa - Checking binary compatibility against previous library versions 
+
+The [Migration Manager for Scala](https://github.com/typesafehub/migration-manager) (MiMa) is a tool for diagnosing binary incompatibilities between different library versions.  


This is now https://github.com/lightbend/migration-manager

gmethvin · 2017-12-20T10:27:52Z

_overviews/tutorials/binary-compatibility-for-library-authors.md

+
+* If backward **binary compatibility** is broken, **major version number** must be increased.
+* If backward **source compatibility** is broken, **minor version number** must be increased.
+* A change in **patch version number** signals **no binary nor source incompatibility**. 


The wording is is a bit weird here. This should be "neither binary nor source incompatibility" or "no binary or source incompatibility".

gmethvin · 2017-12-20T10:33:57Z

_overviews/tutorials/binary-compatibility-for-library-authors.md

+In the following section, we will outline a versioning scheme based on Semantic Versioning that we **strongly encourage** you to adopt for your libraries. The rules listed below are **in addition** to 
+Semantic Versioning v2.0.0.
+
+### Recommended Versioning Scheme


I would also like to encourage projects to document their versioning scheme and binary compatibility rules. Can we add a short section suggesting how a project might do this? If it follows this scheme, we should recommend linking to this document in the README. If not, the README should ideally include a short section explaining the rules for that project.

I'm trying to keep the word count down to not dilute the main takeaways of this tutorial.

I think having another "maintaining an OSS Scala project" guide will be a good place to cover topics such as publishing to repositories and documenting versioning schemes. Speaking of which, I think it's a good idea to name this versioning scheme (e.g. "Scala Binary SemVer") instead of "that versioning scheme mentioned in that tutorial"

I agree, while @gmethvin's suggestion is good I think it may be too much for this guide.

gmethvin · 2017-12-20T10:34:43Z

_overviews/tutorials/binary-compatibility-for-library-authors.md

+## Versioning Scheme - Communicating compatibility breakages
+
+Library authors use versioning schemes to communicate compatibility guarantees between library releases to their users. Versioning schemes like [Semantic Versioning](http://semver.org/)(SemVer) allow
+users to easily reason about the impact of updating a library, without needing to read the detailed release note.


"...release notes."

gmethvin · 2017-12-20T10:48:34Z

_overviews/tutorials/binary-compatibility-for-library-authors.md

+* Need to fetch and bundle multiple library versions when only one is actually used
+* Unexpected runtime behavior if the order of class files changes
+
+Therefore, when resolving JARs to use for compilation and packaging, most build tools will pick only one version of each library and **evict** the rest.


It might be useful to explain that the default scheme for this in sbt (and gradle, and many other build tools) is to take the latest version, since most libraries are backwards but not forwards compatible.

I did initially mention this but was asked to remove it. What do you think @jvican?

I believe you can add "The most common solution in build tools is to take the latest version (sbt, gradle, etc)." and will still be good 👍

jvican · 2017-12-25T00:33:24Z

Okay, I think it’s about time to merge this PR, what’s your take on this? @jatcwang

… minor updates/rewording

- merge conclusion and Explanation for versioning scheme - adjust colors so they don't hurt my eye - various fixes for clarity and accuracy

jatcwang · 2017-12-27T14:13:22Z

@jvican, I've addressed some stuff @gmethvin picked up. (there's one question about mentioning SBT/maven's default eviction strategy - I can add it if you think it's good)

Also just want to make sure that the page is indexable by search engine bots, but we can just merge it and see whether it appears :)

heathermiller · 2018-01-09T00:05:05Z

@jvican please let me know when we can merge this :)

sjrd

Just one minor comment. Good enough for me otherwise.

sjrd · 2018-01-09T12:25:59Z

_overviews/tutorials/binary-compatibility-for-library-authors.md

+* `v1.0.0 -> v2.0.0` is <span style="color: #c10000">binary incompatible</span>. 
+  End users and library maintainers need to update all their dependency graph to remove all dependency on `v1.0.0`.
+* `v1.0.0 -> v1.1.0` is <span style="color: #2b2bd4">binary compatible</span>. Classpath can safely contain both `v1.0.0` and `v1.1.0`. End user may need to fix minor source breaking changes introduced
+* `v1.0.0 -> v1.0.1` is <span style="color: #2b2bd4">binary compatible</span>. This is a safe upgrade that does not introduce binary or source incompatibilities.


is source and binary compatible

jvican · 2018-01-09T21:43:50Z

Well, after 153 comments (without including this one), it's time to ship this valuable guide. Once again, I thank you for this awesome work, this is an unprecedent contribution from the Community and I'm really happy to see that there exists tenacious people out there that help us improve Scala 😄.

SethTisue · 2018-01-09T21:59:15Z

kudos to @jatcwang for tackling this and to everybody for the inspiring group effort here

jatcwang · 2018-01-10T00:31:52Z

Thanks for all your help. Every suggestion and comment was appreciated :) and also thanks for all your awesome work in the scala ecosystem - many silent users like me appreciate it :)

jatcwang changed the title ~~Guide on binary compatibility for library authors~~ [WIP] Guide on binary compatibility for library authors Sep 11, 2017

ktoso reviewed Sep 12, 2017

View reviewed changes

DaniRey reviewed Sep 12, 2017

View reviewed changes

jvican reviewed Sep 12, 2017

View reviewed changes

jvican reviewed Oct 19, 2017

View reviewed changes

jvican reviewed Oct 29, 2017

View reviewed changes

sjrd requested changes Oct 30, 2017

View reviewed changes

jatcwang changed the title ~~[WIP] Guide on binary compatibility for library authors~~ Guide on binary compatibility for library authors Nov 12, 2017

gmethvin reviewed Dec 20, 2017

View reviewed changes

jatcwang added 7 commits December 28, 2017 00:08

Guide on binary compatibility for library authors

0f11be5

fix typos and spelling mistakes

8746ef6

various rewordings and grammar fixes

dbe3fbc

Added "Evolving code without breaking binary compatibility" section +…

61695cf

… minor updates/rewording

Addressing feedback from jvican

8aeac02

Update headers & page location

4b23622

Various rewording and grammar fixes as suggested by jvican

3cbd13d

jatcwang added 4 commits December 28, 2017 00:08

reword reason why evictions are performed by build tools

e5f1019

correct point about not inlining, as inlining from source is safe

1d1c480

- Add scala.js/native section

3710908

- merge conclusion and Explanation for versioning scheme - adjust colors so they don't hurt my eye - various fixes for clarity and accuracy

Address @gmethvin's feedback: fix Mima link, wording and typos

756fab8

jatcwang force-pushed the master branch from 28dc028 to 756fab8 Compare December 27, 2017 14:09

mention default eviction strategy of SBT and gradle

a41fbfc

sjrd approved these changes Jan 9, 2018

View reviewed changes

minor edit

6acae7c

jvican merged commit d8c24c9 into scala:master Jan 9, 2018

jvican mentioned this pull request Jan 14, 2018

A guide to binary compatibility for library authors #621

Closed


		![Initial dependency graph]({{ site.baseurl }}/resources/images/library-author-guide/before_update.png){: style="width: 280px; margin: auto; display: block;"}

		Some time later, we see `B v1.1.0` is now available and we upgraded the version in our `build.sbt`. Our code compiles and seems to work so we push it to production and goes home for dinner.


		## The JVM execution model

		Code compiled to run on the JVM is compiled to a platform-independent format called JVM bytecode and stored in Class File format (with `.class` extension) and these class files are stored


		## Versioning Scheme - Communicate binary compatibility breakages

		We recommend using the following schemes to communicate binary and source compatibility to your users:


		TODO

		## Versioning Scheme - Communicate binary compatibility breakages


		We recommend using the following schemes to communicate binary and source compatibility to your users:

		* Any release with the same major version are Binary Backwards Compatible with each other


		### Explanation

		Why do we use the major version number to signal binary compatibility releases?


		## What are Evictions, Source Compatibility and Binary Compatibility?

		### Evictions


		These are what we call Binary Incompatibility Errors. An error caused by binary incompatibility happens when the compiled bytecode references a name that cannot be resolved during runtime

		## What are Evictions, Source Compatibility and Binary Compatibility?


		## Why binary compatibility matters

		Binary Compatibility matters because failing to maintain it makes life hard for everyone.


		Binary Compatibility matters because failing to maintain it makes life hard for everyone.

		* End users has to update all library versions in their whole transitive dependency tree such that they are binary compatible, otherwise binary compatibility errors will happen at runtime


		Some time later, we see `B v1.1.0` is available and upgrade its version in our build. Our code compiles and seems to work so we push it to production and go home for dinner.

		Unfortunately at 2am, we got frantic calls from customers saying that our application is broken! Looking at the logs, you find lots of `NoSuchMethodError` is being thrown by some code in `A`!


		## Why binary compatibility matters

		Binary Compatibility matters because breaking binary compatibility have bad consequences on the ecosystem around the software.

		you have accidentally introduced binary incompatible changes. Detailed instruction on how to use the SBT plugin can be found in the link.

		We strongly encourage every library author to incorporate MiMa into their library release workflow.


		* Ensure major versions of all versions of a library in the dependency tree are the same
		* Pick the latest version and evict the rest (This is the default behavior of SBT).


		From our [example](#why-binary-compatibility-matters) above, we have learned two important lessons:

		* Binary incompatibility releases often leads to dependency hell, rendering your users unable to update any of their libraries without breaking their application


		### Recommended Versioning Scheme

		* If backward binary compatibility is broken, major version number must be increased


		## MiMa - Checking binary compatibility against previous library versions

		The [Migration Manager for Scala](https://github.com/typesafehub/migration-manager) (MiMa) is a tool for diagnosing binary incompatibilities between different library versions.

Guide on binary compatibility for library authors #881

Guide on binary compatibility for library authors #881

Conversation

jatcwang commented Sep 11, 2017 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

jvican left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

jvican Sep 12, 2017 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

jvican Sep 12, 2017 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

jvican commented Sep 12, 2017 • edited Loading

sjrd commented Sep 12, 2017

jatcwang commented Sep 13, 2017

jatcwang commented Sep 26, 2017

jvican commented Sep 26, 2017

jatcwang commented Oct 1, 2017

heathermiller commented Oct 3, 2017

heathermiller commented Oct 3, 2017

jvican left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

jatcwang commented Oct 21, 2017

heathermiller commented Oct 27, 2017

heathermiller commented Oct 27, 2017

jvican left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

jvican Oct 29, 2017 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

jatcwang commented Sep 11, 2017 •

edited

Loading

jvican Sep 12, 2017 •

edited

Loading

jvican Sep 12, 2017 •

edited

Loading

jvican commented Sep 12, 2017 •

edited

Loading

jvican Oct 29, 2017 •

edited

Loading

jvican Oct 29, 2017 •

edited

Loading