wip: 2.12.0 final release notes

Author: adriaanm

hand-written.md

@@ -1,29 +1,16 @@
-We are happy to announce the availability of Scala 2.12.0-RC2!
+We are happy to announce the availability of Scala 2.12.0!
 
-This RC fixes all reported regressions since 2.11.
-It will become the final by October 28th, unless we hear of any issues that block your upgrade to 2.12 before then!
+The Scala 2.12 compiler has been completely overhauled to make use of the new VM features available in Java 8. A trait is compiled to an interface with default methods for improved binary compatibility. We've unified the treatment of Scala's built-in function types and Single Abstract Method types (for overload resolution, type inference and code generation). Specifically, code generation for function literals uses `invokedynamic` to avoid emitting a classfile at compile time. Many of these features were developed in fruitful collaboration with the Dotty team.
 
+Lukas has delivered a powerful new optimizer with this release, built on earlier work by Miguel Garcia. Many more  (effectively) final methods, including those defined in objects and traits, are now inlined. As well, closure allocations, dead code and [box/unbox pairs](https://github.com/scala/scala/pull/4858) are eliminated more effectively.
 
-Here are the [most noteworthy fixes](https://github.com/scala/scala/pulls?q=is%3Apr+is%3Amerged+milestone%3A2.12.0-RC2+label%3Arelease-notes) since RC1:
+From now on, 2.12.x releases will be fully binary compatible. This release is identical to 2.12.0-RC2. To run Scala 2.12 code, you need a Java 8 runtime.
 
-  - [#5429](https://github.com/scala/scala/pull/5429) Default `-Xmixin-force-forwarders` to `true` (regression in performance of generated code);
-  - [#5398](https://github.com/scala/scala/pull/5398) [SD-225](https://github.com/scala/scala-dev/issues/225) Use a `lzycompute` method for module initialization. Address a performance regression;
-  - [#5417](https://github.com/scala/scala/pull/5417) [SD-233](https://github.com/scala/scala-dev/issues/233) `synchronized` blocks are JIT-friendly again;
-  - [#5433](https://github.com/scala/scala/pull/5433) Don't deprecate `Either.left` and `Either.right` yet;
-  - [#5392](https://github.com/scala/scala/pull/5392) [SI-9918](https://issues.scala-lang.org/browse/SI-9918) Don't crash on `object` in `trait` mixed into package object;
-  - [#5397](https://github.com/scala/scala/pull/5397) [SI-9920](https://issues.scala-lang.org/browse/SI-9920) Avoid linkage errors with captured local objects + self types;
-  - [#5430](https://github.com/scala/scala/pull/5430) Emit `object` in method like `lazy val`;
-  - [#5442](https://github.com/scala/scala/pull/5442) [SI-9943](https://issues.scala-lang.org/browse/SI-9943) `sealed` class does not yield SAM type;
+Our [roadmap](https://github.com/scala/scala/milestones) lists the following upcoming releases for 2016: 2.12.1 will be out shortly (by the end of November) to address some known (but rare) issues in 2.12.0, and 2.11.9 is the last planned 2.11.x release (due by mid December). In the next few weeks, we at Lightbend will share our plans for Scala 2.13.
 
-The [RC1 release notes](http://scala-lang.org/news/2.12.0-RC1) have a list of important changes since M5.
-
-
-In total, we merged [29 pull requests](https://github.com/scala/scala/pulls?q=is%3Apr+is%3Amerged+milestone%3A2.12.0-RC2).
-This milestone resolves [6 JIRA tickets](https://issues.scala-lang.org/issues/?jql=project%20%3D%20SI%20AND%20status%20%3D%20CLOSED%20AND%20resolution%20%3D%20Fixed%20AND%20fixVersion%20%3D%20%22Scala%202.12.0-RC2%22%20ORDER%20BY%20component%20ASC%2C%20priority%20DESC) and [9 scala-dev issues](https://github.com/scala/scala-dev/milestone/9?closed=1).
-
-As usual for Scala pre-releases, 2.12.0-RC2 is not guaranteed to be binary compatible with any other Scala version, including any 2.12 milestones and release candidates.
 
 ### Known issues
+There are some [known issues](https://issues.scala-lang.org/issues/?jql=project%20%3D%20SI%20and%20affectedVersion%20%3D%20%22Scala%202.12.0%22%20and%20status%20%3D%20open) with this release that [will be resolved](https://github.com/scala/scala/pulls?q=is%3Aopen+is%3Apr+milestone%3A2.12.1+label%3Arelease-notes) in 2.12.1, due out by the end of November.
 
 As with previous 2.12 builds, the new trait encoding may make some
 trait-based code run slower. We've investigated this issue in depth,
@@ -42,18 +29,17 @@ We hope to address the following in a future 2.12.x release:
 
 ## Scala 2.12
 
-Scala 2.12 requires a Java 8 runtime.
+Scala 2.12 is all about making optimal use of Java 8's new features (and thus generates code that requires a Java 8 runtime).
+  - Traits ([#5003](https://github.com/scala/scala/pull/5003)) and functions are compiled to their Java 8 equivalents.
+  - We treat Single Abstract Method types and Scala's builtin function types uniformly from type checking to the back end ([#4971](https://github.com/scala/scala/pull/4971)). We also use `invokedynamic` for a more natural encoding of other language features ([#4896](https://github.com/scala/scala/pull/4896)).
+  - We've standardized on the GenBCode back end ([#4814](https://github.com/scala/scala/pull/4814), [#4838](https://github.com/scala/scala/pull/4838)) and the flat classpath implementation is now the default ([#5057](https://github.com/scala/scala/pull/5057)).
+  - The optimizer has been completely overhauled for 2.12.
 
-Scala 2.12 is all about making optimal use of Java 8's new features. Traits ([#5003](https://github.com/scala/scala/pull/5003)) and functions are compiled to their Java 8 equivalents, and we treat Single Abstract Method types and Scala's builtin function types uniformly from type checking to the back end ([#4971](https://github.com/scala/scala/pull/4971)). We also use `invokedynamic` for a more natural encoding of other language features ([#4896](https://github.com/scala/scala/pull/4896)). We've standardized on the GenBCode back end ([#4814](https://github.com/scala/scala/pull/4814), [#4838](https://github.com/scala/scala/pull/4838)) and the flat classpath implementation is now the default ([#5057](https://github.com/scala/scala/pull/5057)). The optimizer has been completely overhauled for 2.12.
-
-Except for the breaking changes listed below, code that compiles on 2.11.x without deprecation warnings should compile on 2.12.x too, unless you use experimental APIs such as reflection.  If you find incompatibilities, please [file an issue](https://issues.scala-lang.org).
+Except for the breaking changes listed below, code that compiles on 2.11.x without deprecation warnings should compile on 2.12.x too, unless you use experimental APIs such as reflection.  If you find incompatibilities, please [file an issue](https://issues.scala-lang.org). Cross-building is a one-line change to most sbt builds, and even provides support for [version-specific source folders](http://www.scala-sbt.org/0.13/docs/sbt-0.13-Tech-Previews.html#Cross-version+support+for+Scala+sources) out of the box, when necessary to work around incompatibilities (e.g. macros).
 
 ### New features
+Here are the [most noteworthy pull request](https://github.com/scala/scala/pulls?utf8=%E2%9C%93&q=%20is%3Amerged%20label%3A2.12%20label%3Arelease-notes%20) of the 2.12 release. See also the [RC2](http://scala-lang.org/news/2.12.0-RC2) and [RC1](http://scala-lang.org/news/2.12.0-RC1) release notes for the most recent changes.
 
-With this release candidate, we consider 2.12.x to be feature complete.
-
-For 2.12.0, we will try to remain binary compatible with RC1,
-and we won't risk regressions except for the most critical bugs.
 
 #### Trait compiles to an interface
 
@@ -154,6 +140,10 @@ You can get the old behavior with `-Xsource:2.11`.  This may be
 useful for testing whether these changes are responsible if your
 code fails to compile.
 
+[Lazy vals and objects](https://github.com/scala/scala/pull/5294) have been reworked,
+and those defined in methods now use a [more efficient representation](https://github.com/scala/scala/pull/5374)
+that allows synchronization on the holder of the `lazy val`, instead of the surrounding class (as in Dotty).
+
 #### Changed syntax trees (affects macro and compiler plugin authors)
 
 PR [#4794](https://github.com/scala/scala/pull/4749) changed the syntax trees for selections of statically accessible symbols. For example, a selection of `Predef` no longer has the shape `q"scala.this.Predef"` but simply `q"scala.Predef"`. Macros and compiler plugins matching on the old tree shape need to be adjusted.
@@ -162,27 +152,27 @@ PR [#4794](https://github.com/scala/scala/pull/4749) changed the syntax trees fo
 
 ## Binary compatibility
 
-Since Scala 2.11, minor releases of Scala are binary compatible with each other.
+Since Scala 2.11, minor releases of Scala are binary compatible with each other. The [Scala 2.11.1 release notes](http://scala-lang.org/news/2.11.1) explain in more detail on how binary compatibility works in Scala.
 Scala 2.12 will continue this tradition: every 2.12.x release will be binary compatible with 2.12.0.
-Milestones and release candidates, however, are **not** binary compatible with any other release.
-
-Scala 2.12 is not and will not be binary compatible with the 2.11.x series.  This allows us to keep improving the Scala compiler and standard library.  We are working with the community to ensure that core projects in the Scala eco-system become available for 2.12.  Please refer to this growing [list of libraries and frameworks](https://github.com/scala/make-release-notes/blob/2.12.x/projects-2.12.md).
 
-The [Scala 2.11.1 release notes](http://scala-lang.org/news/2.11.1) explain in more detail on how binary compatibility works in Scala.  The same policies apply to 2.12 as well.
+Although Scala 2.11 and 2.12 are mostly source compatible to facilitate cross-building, they are not *binary* compatible.  This allows us to keep improving the Scala compiler and standard library.  We are working with the community to ensure that core projects in the Scala eco-system become available for 2.12.  Please refer to this growing [list of libraries and frameworks](https://github.com/scala/make-release-notes/blob/2.12.x/projects-2.12.md).
 
 
 ## Contributors
 
 A big thank you to everyone who's helped improve Scala by reporting bugs, improving our documentation, spreading kindness in mailing lists and other public fora, and submitting and reviewing pull requests! You are all magnificent.
 
-According to `git shortlog -sn --no-merges v2.12.0-RC1..v2.12.0-RC2`, the following contributors helped to realize this release candidate: Adriaan Moors, Jason Zaugg, Lukas Rytz, Seth Tisue, Stefan Zeiger, Antoine Gourlay, Raphael Jolly. Thank you!
+Scala 2.12.0 is the result of merging over [500 pull requests](https://github.com/scala/scala/pulls?utf8=%E2%9C%93&q=is%3Amerged%20label%3A2.12%20) out of about [600 received PRs](https://github.com/scala/scala/pulls?utf8=%E2%9C%93&q=is%3Apr%20label%3A2.12%20). The [contributions to 2.12.x over the last 2 years](https://github.com/scala/scala/graphs/contributors?from=2014-11-01&to=2016-10-29&type=c) [break down](https://docs.google.com/spreadsheets/d/16zVViCpJEZn_x2RlYFh-xAOiHJG3SrYYpfetRr5cu_Y/edit#gid=912693440) as 64/32/4 between the Scala team at Lightbend (lrytz, retronym, adriaanm, SethTisue, szeiger), the community and EPFL.
+
+Thank you very much to all contributors that helped realize this Scala release!
+
 
 ## Release notes
 
 Improvements to these release notes [are welcome!](https://github.com/scala/make-release-notes/blob/2.12.x/hand-written.md)
 
 ## Obtaining Scala
-
-* Download a distribution from [scala-lang.org](http://scala-lang.org/download/2.12.0-RC2.html)
-* Bump the `scalaVersion` setting in your sbt-based project
-* Obtain JARs via [Maven Central](http://search.maven.org/#search%7Cga%7C1%7Cg%3A%22org.scala-lang%22%20AND%20v%3A%222.12.0-RC2%22)
+* Install a Java 8 runtime (Java 9 is not yet supported).
+* Download a distribution from [scala-lang.org](http://scala-lang.org/download/2.12.0.html)
+* Bump the `scalaVersion` setting in your sbt-based project. We recommend upgrading to 0.13.13 for [faster compilation](https://github.com/sbt/sbt/pull/2754) and much more!
+* Obtain JARs via [Maven Central](http://search.maven.org/#search%7Cga%7C1%7Cg%3A%22org.scala-lang%22%20AND%20v%3A%222.12.0%22)