scala/make-release-notes

notes on possible 2.12 release notes improvements

SethTisue opened this issue · 24 comments

SethTisue commented

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 commented
adriaanm commented
  • mention what's next (last 2.11 release: 2.11.9), 2.12.1 -- both before end of year.
adriaanm commented

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

SethTisue commented

there's also #151

lrytz commented

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 commented

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 commented
  • Known issues: JIRA query for issues affecting 2.12.0 without a fix version
adriaanm commented

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 commented
  • Please mention that -Ypartial-unification should be used in preference to -Xexperimental until all the mystery meat has been removed from that flag.
adriaanm commented

Thanks, will do.

SethTisue commented
  • "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 typelevel/scalacheck#290 (comment))
lrytz commented

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

sjrd commented

Can we have a Scala.js-specific section somewhere? The SAM treatment and the improved val type inference have significant impact on Scala.js users (more so than generically for the JVM). It might be a good idea to point that out in the release notes. I'm already getting questions about what 2.12 brings for Scala.js, so people actually want to know that. I can prepare a small section if you would be interested in including it.

  • 👍1
lrytz commented

Do you already have that written up in a doc to which we could link? I think it would be good to have a phrase or two, with a link to learn more (if there's more to it than just a phrase or two).

sjrd commented

I don't have anything written up yet, but I can do that tomorrow.

lrytz commented

That would be great. I think we're planning to announce tomorrow.

adriaanm commented

Let's move some of the remaining issues into the scala-seed template. Would like to have this be a nice evolving demo of the various new features in 2.12

sjrd commented

OK here is a quick small draft of a section on Scala.js. I would suggest putting this as a last sub-section under the section "New language features", so at the same heading level as "Parameter names available at runtime". It is a bit more than "just a phrase or two" that you requested, but it still is in the same ballpark size as the other sub-sub-section of the same level.

Better type inference for Scala.js

Thanks to SAMs, parameter types are now inferred for js.Functions. For example, you can now write:

dom.window.requestAnimationFrame { now => // inferred as Double
  ...
}

without having to specify (now: Double) explicitly. In a similar spirit, the new inference for overriding vals allows to more easily implement Scala.js-defined JS traits with anonymous objects. For example:

@ScalaJSDefined
trait SomeOptions extends js.Object {
  val width: Double | String // e.g., "300px"
}
val options = new SomeOptions {
  val width = 200 // implicitly converted from Int to the inferred Double | String
}

Markdown code:

#### Better type inference for Scala.js

Thanks to SAMs, parameter types are now inferred for `js.Function`s. For example, you can now write:
```scala
dom.window.requestAnimationFrame { now => // inferred as Double
  ...
}
```

without having to specify `(now: Double)` explicitly. In a similar spirit, the new inference for overriding `val`s allows to more easily implement Scala.js-defined JS traits with anonymous objects. For example:
```scala
@ScalaJSDefined
trait SomeOptions extends js.Object {
  val width: Double | String // e.g., "300px"
}
val options = new SomeOptions {
  val width = 200 // implicitly converted from Int to the inferred Double | String
}
```
lrytz commented

@sjrd thanks! Added to the PR: 8f46e6b

sjrd commented

Thanks awesome 👍

milessabin commented

shapeless 2.3.2 and macro-compat 1.1.1 now published for 2.12.0.

  • 🎉1
lrytz commented

oh, i got the url wrong. thanks :)