scala/make-release-notes

The project that generates Scala release notes.

Scala Release Notes Creator

This project generates the HTML release notes for Scala. Its goal is to be minimal and sufficient. Not an ideal example of Scala code, but perhaps shows off a few standard library APIs.

Building

1. Update the highlights notes in hand-written.md.
2. run sbt, and then:

> runMain MakeReleaseNotes $PrevVersion $CurrentVersion $ReleaseYear/$ReleaseMonth/$ReleaseDay "$pathToScalaScalaCheckout"

Contributing

Feel free to improve. Make sure to sign the Scala CLA.

make-release-notes's Issues

document SI-8358 scala-xml is on boot classpath by default

https://issues.scala-lang.org/browse/SI-8358

proper credit

github's contributors doesn't list everyone (reported by Scott Carey)

do

git log --no-merges --since='2013-01-01' --format='%aN'  | sort | uniq -c | sort -rn

include `api_docs:` line in scala-lang PR

as per scala/scala-lang#1352

scaladex for 2.13.0-M3 does not work

This document https://github.com/scala/make-release-notes/blob/2.13.x/projects-2.13.md
suggests that

Scaladex, the index of Scala libraries, now offers searching by target version:

• All libraries for 2.13.0-M3

But it does not return any results. Might be a scaladex bug; just wondering whether the idea is still to

edit this page and let the world know what libraries are available.

Why not just rely on scaladex (once it works)?

make hand-written less hand-written

substituted released version, now that jira urls etc all fully capture their queries

scalatest_2.11.0-RC3-2.1.2

Automate maintenance of projects-2.xx.md

Why not just fix indexing in Scaladex to do it regularly and for all known repos instead of manually making the list of libraries and plugins which adopted the latest release?

Generated Markdown files should have comment that describes which script generated it

Given the fact that we generate those files in this project and then use it somewhere else (e.g. in scala-lang) it would be good to include a comment in generated Markdown file that points back at script that generated it.

It would vastly help to understand where given files are coming from when analyzing history of previous releases.

re-iterate colorful REPL

scala/scala#3993 (comment)

notes on possible 2.12 release notes improvements

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.

Available Projects for Scala 2.12 vs Scaladex

Hi guys regarding: https://github.com/scala/make-release-notes/blob/2.12.x/projects-2.12.md#scala-2120-rc2

In the index we have 155 projects for 2.12:
https://index.scala-lang.org/search?q=targets%3Ascala_2.12&page=1&sort=stars

detailed text on binary compatibility should be separate from release announcement

right now in both 2.11.x and 2.12.0-Mx release notes we just link to the 2.11.1 notes. the text in question should have a better, more permanent home by the time 2.12.0 is done.

wrong entity encoding

https://github.com/scala/scala-lang/pull/158/files#diff-05cd5b883baddc8b0ef75cedf4376776R101

not sure how this happened -- i ran sbt using the utf8 encoding

Catalysts on 2.13.0-M3

see https://index.scala-lang.org/typelevel/catalysts/catalysts/0.6?target=_2.13.0-M3

But the cats build fails - see typelevel/cats#2203

The PR adds the build as allowed to fail on Travis, with the hope we can get "most" of the changes in if we have to wait for next Mrelease. Any thoughts on the issue, btw?

Add permalink to generate release notes

See scala/scala-lang#242 (comment) for an example.

note SI-4577

mention homebrew and dash?

Add Typesafe logging

https://twitter.com/hseeberger/status/443702384926425088

Resolve release date from tag on GitHub

If you leave out the release date parameter for MakeDownloadPage it'll just take current date. That's probably not what you want because we should use date of when the tag was created.

It's possible to resolve it using GitHub's API:

curl -s https://api.github.com/repos/scala/scala/git/refs/tags/v2.11.0-M5 | json object.url | xargs curl -s | json tagger.date
2013-09-07T00:05:56Z

assuming the jsontool is installed.

//cc @retronym

MakeReleaseNotes.genPR throws exception

Under Windows I get

java.util.NoSuchElementException: key not found: HOME
at scala.collection.MapLike$class.default(MapLike.scala:228)
at scala.collection.AbstractMap.default(Map.scala:58)
at scala.collection.MapLike$class.apply(MapLike.scala:141)
at scala.collection.AbstractMap.apply(Map.scala:58)
at MakeReleaseNotes$.genPR$default$4(MakeReleaseNotes.scala:8)

and after setting HOME I get

java.lang.IllegalArgumentException
at java.util.Date.parse(Unknown Source)
at java.util.Date.(Unknown Source)
at MakeReleaseNotes$.genPR(MakeReleaseNotes.scala:9)

So I cannot add my library:(.

Thanks, Peter

Separate "Available Projects" pages

Just skim-reading I didn't notice that halfway into https://github.com/scala/make-release-notes/blob/2.13.x/projects-2.13.md it switches from "Available Projects for Scala 2.13.0-M4" to "Available Projects for Scala 2.13.0-M3".

Should we split the pages? If so split into M3 and M4 pages, or just split the M3 part out of the general projects-2.13.md page? Or just dump the M3 content?

I can do the work.

updating download/index.md should be automated

currently the script just says:

src/main/scala/MakeReleaseNotes.scala: println(s"# don't forget to\n${scala.util.Properties.envOrElse("EDITOR", "mate")} ../scala-lang/download/index.md ../scala-lang/documentation/api.md ../scala-lang/_config.yml")

but the manual changes you need to make to download/index.md are annoying