Extract binary compatibility from 2.11.1 release notes

And update it for the upcoming 2.12.0.

Author: adriaanm

documentation/compatibility.md

@@ -0,0 +1,19 @@
+## Binary Compatibility
+When two versions of Scala (such as 2.12.0 and 2.12.1) are binary compatible, it is safe to compile your project on one Scala version and link against another Scala version at run time. Safe run-time linkage (only!) means that the JVM does not throw a (subclass of) [`LinkageError`](http://docs.oracle.com/javase/7/docs/api/java/lang/LinkageError.html) when executing your program in the mixed scenario, assuming that none arise when compiling and running on the same version of Scala. Concretely, this means you may have external dependencies on your run-time classpath that use a different version of Scala than the one you're compiling with, as long as they're binary compatibile. In other words, separate compilation on different binary compatible versions does not introduce problems compared to compiling and running everything on the same version of Scala.
+
+We check binary compatibility automatically with [MiMa](https://github.com/typesafehub/migration-manager). We strive to maintain a similar invariant for the `behavior` (as opposed to just linkage) of the standard library, but this is not checked mechanically (Scala is not a proof assistant so this is out of reach for its type system).
+
+### Forwards and Back
+We distinguish forwards and backwards compatibility (think of these as properties of a sequence of versions, not of an individual version). Maintaining backwards compatibility means code compiled on an older version will link with code compiled with newer ones. Forwards compatibility allows you to compile on new versions and run on older ones.
+
+Thus, backwards compatibility precludes the removal of (non-private) methods, as older versions could call them, not knowing they would be removed, whereas forwards compatibility disallows adding new (non-private) methods, because newer programs may come to depend on them, which would prevent them from running on older versions (private methods are exempted here as well, as their definition and call sites must be in the same compilation unit).
+
+### Meta
+It is not common, but possible, that compiling the same code base with different (but compatible) versions of the Scala compiler yields binary incompatible artifacts. For example, the optimizer (by design) does not guarantee compatibility. Similarly, compiling on different JVM versions could yield incompatible artifacts. This is rare, and we try to avoid it, but we can't guarantee it will never happen, as this is not a property we can check mechanically.
+
+If you aim to maintain binary compatibility in your own project, you should run MiMa yourself when releasing a new version.
+
+#### Concretely
+For a fixed major version N (currently, `N=12`), we guarantee forwards and backwards compatibility of the `"org.scala-lang" % "scala-library" % s"2.$N.x"` and `"org.scala-lang" % "scala-reflect" % s"2.$N.x"` artifacts, except for anything under subpackages named `internal` or `impl`, such as the `scala.reflect.internal` package, as scala-reflect as a whole remains experimental. We also strongly discourage relying on the stability of `scala.concurrent.impl` and `scala.reflect.runtime`, though we will only break compatibility here for critical bugs.
+
+Note that we will only enforce *backwards* binary compatibility for new modules (artifacts under the groupId `org.scala-lang.modules`). Because they are opt-in, it's less of a burden to require having the latest version on the classpath. (Without forward compatibility, the latest version of the artifact must be on the run-time classpath to avoid linkage errors.)