notes on possible 2.12 release notes improvements

[SethTisue]

here is a mass of rough notes I've been accumulating. making a ticket since it's looking like I won't have time for it this week or next week

• if sbt 0.13.13 comes out before 2.12 does, maybe mention that upgrading will give you better/faster incremental compilation (it does, right?)
• it already says "This leads to significantly smaller JAR files", maybe add an example pair of before and after numbers (e.g. how much did scala-library.jar shrink?)
• "cross-building" is not mentioned in the current release notes. allowing 2.11/2.12 cross-building was a major theme of 2.12. the original 2.12 roadmap was explicit about this, so it might just be a matter of borrowing text for that. (and perhaps there is text there on other subjects to be borrowed, as well.) the 2.12 notes are for a broad audience, so we shouldn't assume they have read (and actually remember!) a roadmap we announced so long ago
  • maybe mention sbt's support for cross-version building (including using CrossVersion.partialVersion to have different source directories?)
• is the material on the binary-compatibility implications of the 2.12 trait encoding sufficient? I've seen this come up in the chat rooms several times, that people aren't sure what they can or can't do
  • related: we might want to mention that MiMa has been updated to understand the new coding (and say what minimum version of MiMa to use)
• there is already some text about SAMs, but some additional changes were made during the RC phase so that text might need revisiting
  • you're writing a library in Scala. you want it to cross compile in 2.11 and 2.12 (let's assume you don't want to use the -Xexperimental stuff in 2.11, and you probably shouldn't!), but also want the API to be usable from Java 8. what happens when you try to use overloads. Iulian had an example in the SAM PR (4971), there's the community build failures, etc.
  • Jason points out that it might be instructive to make a comparative example for calling a Java API that uses overloading, and see how Java does when calling that API from Java 8 code, and how we do.
  • Sebastien found something where we need to exclude classes that have SAM trait parents, because LambdaMetaFactory will only instantiate the trait, not the class? Adriaan said there’s also an exclusion for self types. Jason: “specialization we’re excluding”
  • Adriaan: "We should still mention the order of Sam conversion has changed. Also, the improved type inference for function literals passed to HO methods is noteworthy"
• I think the notes could sell the new optimizer harder. this is a banner feature for 2.12, we should be more explicit about why that's so and why it was worth the effort (even just a few sentences might be sufficient)
  • do we need to caution about the optimizer and incremental and/or separate compilation? (iirc with the default settings it's OK but with some settings you have to recompile everything?)
• tout scala-java8-compat? it isn't mentioned, people may not be aware
• Lukas blogged over the summer about "Performance of using default methods to compile Scala trait methods”, probably the notes should have some summary of what final state was reached on this. there is some text about possible decreased performance, maybe that just needs to be checked.
• release-note the special JUnit @Test hack? no longer necessary, as we generate forwarders unconditionally.

[dwijnand]

• sbt 0.13.13 will be out this Friday (touch wood)
• here's a link for the compile speedup Jason contributed SD-232 Recycle classloaders to be anti-hostile to JIT sbt/sbt#2754
• sbt already has built-in support for cross-version sources as of 0.13.8: http://www.scala-sbt.org/0.13/docs/sbt-0.13-Tech-Previews.html#Cross-version+support+for+Scala+sources

[adriaanm]

• mention what's next (last 2.11 release: 2.11.9), 2.12.1 -- both before end of year.

[adriaanm]

Thanks for collecting these, @SethTisue! I will consolidate into the final release notes.

[SethTisue]

there's also #151

[lrytz]

it already says "This leads to significantly smaller JAR files", maybe add an example pair of before and after numbers (e.g. how much did scala-library.jar shrink?)

From my scala world slides (https://dl.dropboxusercontent.com/u/4881107/website/scala-world-2016.pdf)

• 2.11.8: 5.5M
• M3 5.4M
• M4 5.0M
• M5 4.4M
• RC1 4.3M

Unfortunately, with mixin forwarders RC2 is at 5.2M.

Maybe scala-library is also not the best benchmark because 1) the amount of mixin forwarders, and 2) it's compiled with the opimizer / inliner, leading to code duplication.

[adriaanm]

• Porting Stefan's notes from 2.12 release notes scala-dev#101:

sbt-based build

The old ant-based build system has been removed from the main Scala repository in favor of an sbt-based build. This makes it easier to get started hacking on the compiler and standard library. All you need on your machine is JDK 8 and sbt - no ant, no environment variables to set, no shell scripts to run. You can build, use, test and publish Scala like any other sbt-based project.

scala-java8-compat

The Java 8 compatibility module for Scala has received an overhaul for Scala 2.12. Even though interoperability of Java 8 SAMs and Scala functions is now baked into the language, this module provides additional convenience for working with Java 8 SAMs. Java 8 streams support was also added during the development cycle of Scala 2.12. Releases are available for both, Scala 2.11 and Scala 2.12.

[adriaanm]

• Known issues: JIRA query for issues affecting 2.12.0 without a fix version

[adriaanm]

deadlines:

• quite a few 2.12.1 PRs already submitted and merged, one more week (until Nov 7) to submit final fixes, will then focus on drilling down queue for a Nov 30 release
• 2.11.9 is the last planned 2.11.x release, due by mid-December

[milessabin]

• Please mention that -Ypartial-unification should be used in preference to -Xexperimental until all the mystery meat has been removed from that flag.

[adriaanm]

Thanks, will do.

[SethTisue]

• "New in 2.12 is that locking behavior is now different when lambdas are involved, as the lambda body is lifted to a member of the enclosing class (and thus an invocation blocks on the object's initialization lock), instead of a method in a separate (anonymous) class." (@adriaanm at Deadlock with ScalaCheck 1.13.x, scalaz-concurrent, and Scala 2.12.0-RC2 typelevel/scalacheck#290 (comment))

[lrytz]

a few more from the PR list with release-notes label - we don't necessarily need to include them all, just consider:

• Avoid inlining calls to sun.reflect.CallerSensitive annotated methods (Avoid inlining calls to sun.reflect.CallerSensitive annotated methods scala-dev#33)
• deprecate eta-expansion of zero-arg method values SI-7187 deprecate eta-expansion of zero-arg method values scala#5327
• Propagate overloaded function type to expected arg type Propagate overloaded function type to expected arg type scala#5307
• Deprecate JavaConversions SI-9684 Deprecate JavaConversions scala#5109
• Improve performance and behavior of ListMap and ListSet -- traversal is now in insertion order! Improve performance and behavior of ListMap and ListSet scala#5103
• Add doc annotation @shortDescription to enable explicit synopsis Add doc annotation @shortDescription to enable explicit synopsis scala#4991
• add doc annotation to hide specific conversions SI-9620: add doc annotation to hide specific conversions scala#4952
• Pattern Matching analysis improvements Pattern Matching analysis improvements scala#4919
• Make @deprecated{Inheritance,Overriding} public SI-6162 Make @deprecated{Inheritance,Overriding} public scala#4827
• Add an @implicitAmbiguous annotation SI-6806 Add an @implicitAmbiguous annotation scala#4673
• Add an implementation of mutable.TreeMap SI-4147 Add an implementation of mutable.TreeMap scala#4504