Release Scala 2.13.15
Closed this issue · 2 comments
Variables to be expanded in this template (or set and export them in a local terminal, so that you can copy/paste the commands below without replacing anything):
SCALA_VER_BASE="2.13.15"
SCALA_VER_SUFFIX=""
SCALA_SHA=b6f70d2347f2857695e5c0fe544b0f921544b02a
DIST_SHA=4bc3c75fa5155b4070aaf7ba66e1d2f7b6a92b83
SCALA_VER="$SCALA_VER_BASE$SCALA_VER_SUFFIX"
Key links:
- scala/scala milestone: https://github.com/scala/scala/milestones/2.13.15
- scala/bug milestone: https://github.com/scala/bug/milestones/2.13.15
- scala/scala-dev milestone: https://github.com/scala/scala-dev/milestones/2.13.15
- Discourse topic: https://contributors.scala-lang.org/t/scala-2-13-15-release-planning/6649?u=sethtisue
- release notes draft: https://github.com/SethTisue/scala-dev/blob/scala-2.13.15/2.13.15.md
N weeks before the release
- Wind down PR queue. There has to be enough time after the last (non-trivial) PR is merged and the next phase. The core of the eco-system needs time to prepare for the final!
- Triage scala/bug and scala/scala-dev tickets
- Create next scala/scala milestone, move the magical "Merge to 2.12.x" description to it (so Scabot uses it as default for new PRs), move pending PRs
- Create next scala/bug milestone, move pending issues
- Create next scala/scala-dev milestone, move pending issues
- Check PRs assigned to the milestone, also check WIP
- Announce expected release date and current nightly "release candidate" (nightly sha-mangled version) at https://scala-ci.typesafe.com/artifactory/scala-integration/ on https://contributors.scala-lang.org/c/announcements
- Also notify Scala Center advisory board members of the upcoming release, so they can help test if they want (Seth can handle this, if asked)
Release announcement / notes
- Review merged PRs, make sure release-notes label is applied appropriately
- PRs with release-notes label must have excellent title & description (title will be pasted literally in release note bullet list)
- Draft release notes (PR and self-merge, so others can comment there rather than on the commits)
- Starting point:
gh api --paginate -X GET search/issues -f q='repo:scala/scala is:pull-request is:merged milestone:2.12.14 label:release-notes' -q '.items[] | " * \(.title) ([#\(.number)](\(.html_url)) by [@\(.user.login)](\(.user.html_url)))"'
- Starting point:
- On contributors thread, link to release note file and request feedback
N days before release
- Announce no more PRs will be merged unless last-minute regressions are found. Re-iterate current nightly sha version for testing.
- Community build green on JDK 8, 11, 17, 21, 23
- Windows build on GitHub Actions: https://github.com/scala/scala/actions/runs/10482096408
- JDK 17 build on Travis-CI (cron job): https://app.travis-ci.com/github/scala/scala/builds/271974339
- Check any merged PRs accidentally assigned to the next milestone in this branch, and re-assign them to this milestone
- Merge in any older release branch
- Check module versioning (is everything in versions.properties up to date?)
On major release, bump PickleFormat version- Test on Lightbend customer codebase(s), if applicable
- Close the scala/scala and scala/bug milestones
Allow time for testing
How much time is sufficient? A week is a bare minimum. Two weeks is a better "normal" amount. We should also respect requests from Scala Center advisory board members, if they explicitly ask for additional testing time. (In the past, we sometimes only waited a day or two, but this was overly optimistic in presuming that people had been testing nightlies all along.)
Be mindful of others' schedules; even minor releases make work downstream (for Scala.js and Scala Native, for the Scala 3 team, for compiler plugin authors, and so on). And a botched release might make unexpected work for ourselves as well as for others. So it's better not to release on a Friday or even a Thursday, or too close to a major holiday. And it's best to release while everyone in both America and Europe is awake. (First thing in the morning in America is a good choice.)
Stage! (point of soft no-return)
Once sufficient time for community testing has passed, it's time to stage the release!
We call this "soft" no-return because even staged artifacts can end up in local caches and cause confusion.
- Make sure there are no stray staging repos on Sonatype
- Trigger a custom build on travis
- Select the correct branch
- Custom config:
before_script: export SCALA_VER_BASE=$SCALA_VER_BASE SCALA_VER_SUFFIX=$SCALA_VER_SUFFIX
- https://app.travis-ci.com/github/scala/scala/builds/272416681
- Check the build status on https://github.com/scala/scala/commits/2.13.x
- If you get "Server redirected too many times" from Sonatype, you may need to redo the Travis-CI secrets as per #783 (comment) -- this seems to reoccur from time to time for unknown reasons
- Check that the scala/scala job also triggered a following scala/scala-dist job: https://app.travis-ci.com/github/scala/scala-dist/jobs/626378798
- Create the scala/scala tag locally:
git tag -s -m "Scala $SCALA_VER" v$SCALA_VER $SCALA_SHA
- Create scala-dist tag locally:
git tag -s -m "Scala $SCALA_VER" v$SCALA_VER $DIST_SHA
- Note the repos to be promoted after tag is cut (see travis log)
- Sanity check jar/pom
- https://oss.sonatype.org/content/repositories/staging/org/scala-lang/scala-compiler/$SCALA_VER/
- in particular, if the release was staged multiple times, double check that https://oss.sonatype.org/content/repositories/staging/ has the files from the most recent build
- Check that JARs haven't mysteriously bloated — compare sizes to previous release. We have no other backstop for this.
Release! (point of hard no-return)
"Hard" no-return because Maven Central is forever. Also, S3 uploads should be treated as forever (S3 buckets can be changed, but it can takes days to become consistent). Tags, too, should be treated as forever, even though they can technically be deleted and re-pushed.
- Push scala/scala tag:
git push https://github.com/scala/scala.git v$SCALA_VER
- Push scala/scala-dist tag:
git push https://github.com/scala/scala-dist.git v$SCALA_VER
- Trigger two scala-dist jobs on travis (https://app.travis-ci.com/github/scala/scala-dist) with custom config. must use full-length SHAs!
before_script: export version=$SCALA_VER scala_sha=$SCALA_SHA mode=archives
: https://app.travis-ci.com/github/scala/scala-dist/builds/?before_script: export version=$SCALA_VER scala_sha=$SCALA_SHA mode=update-api
: https://app.travis-ci.com/github/scala/scala-dist/builds/?
- Promote staging repos:
st_stagingRepoPromote [scala-repo]
,st_stagingRepoPromote [modules-repo]
(or use oss.sonatype.org web UI)
While waiting for Maven Central
- Prepare PR to https://github.com/scala/scala-lang/ (using scala/make-release-notes which requires a staged release and a pushed tag; refer to PR from previous release as a guide)
_config.yml
(update scalaversion or devscalaversion)_data/scala-releases.yml
- new files in
_downloads
and_posts
- Prepare PR to https://github.com/scala/docs.scala-lang/ (refer to PR from previous release as a guide)
-_config.yml
api/all.md
overviews/FAQ/index.md
contribute/bug-reporting-guide.md
- perhaps
_overviews/jdk-compatibility/overview.md
(online version: https://docs.scala-lang.org/overviews/jdk-compatibility/overview.html)
Find the release on Maven Central
After everything is on Maven Central
- Pre-announce the release on https://contributors.scala-lang.org/c/announcements
-
On major releases only: (manually) update thecurrent
symlink for the API docs - Check that the API docs are published
- https://www.scala-lang.org/api/ should have new version
- if they don't show up, possible troubleshooting steps include:
- review the two scala-dist job logs to make sure that
- the first one appears to have succeeded putting files in
/home/linuxsoft/archives/scala/api
onchara.epfl.ch
- the second one appears to have succeeded in updating the symlink (from
2.1x.y
to $SCALA_VER)
- the first one appears to have succeeded putting files in
- ssh to chara.epfl.ch and poke around to see if things are where they should be
- if you don't have the credential for this locally but you are able to bring jenkins-worker-publish up at
ssh jenkins-worker-publish
, then from there you canssh -i ~/.ssh/jenkins_lightbend_chara scalatest@chara.epfl.ch
- if you don't have the credential for this locally but you are able to bring jenkins-worker-publish up at
- see if https://scala-webapps.epfl.ch/jenkins/view/All/job/production_scala-lang.org-scala-dist-archive-sync/ has run a job yet to sync the changes into production
- if not, you can manually trigger a job. Seth has access to do that, probably others on the team do too. if we get stuck, Fabien can help
- review the two scala-dist job logs to make sure that
Prepare downstream
-
Create PR to add/update spec links on scala-lang.org (example: scala/scala-lang#1050) -
build and release scala-collection-compat and other modules (or open tickets asking that the maintainers do so)this work has moved to https://github.com/scala/make-release-notes/blob/2.13.x/projects-2.13.md
- if it's a 2.12.x release, publish macro paradise for the new version
- Open tickets in these repos, requesting publishing:
- typelevel/kind-projector
- scalameta
- scalafix
- scoverage
- silencer
- wartremover
- acyclic
- Ammonite
- scala-debug-adapter
- scala3-migrate
- scala-cli
- (Lightbend) lightbend/genjavadoc
- in addition to publishing, PR the addition of the new version to CI and add a patch file so nightlies of the next version work in the community build
Wait for downstream
Before proceeding any further, wait for the ecosystem to catch up.
- Downstream publishing:
- Wait for Scala.js to support the new release
- Wait for Scala Native to support the new release
- Wait for scalameta to publish
- Wait for scalafix to publish
- Wait for Metals to publish
- Wait for kind-projector to publish
- Wait for scoverage to publish
- Wait for scala-debug-adapter to publish
- Downstream signoffs:
- Ask the Scala Center to sign off (Seb)
- Ask VirtusLab to sign off (Tomasz)
We have promised to wait 48 non-weekend hours, minimum.
If there are delays downstream, at some point it may make sense to go ahead and announce anyway, since news of the release will already be spreading in the community.
Announcements
- On GitHub, use "Create release from tag" button and add release notes
- Merge the scala-lang PR and the docs.scala-lang.org PR
- wait for them to arrive on the websites and make sure they look okay
- if the scala-lang changes don't show up, possible troubleshooting steps include:
- see if https://scala-webapps.epfl.ch/jenkins/view/All/job/production_scala-lang.org-builder/ has run a job yet to actually publish the changes
- see note above about permissions to trigger a job
- if the scala-lang changes don't show up, possible troubleshooting steps include:
- wait for them to arrive on the websites and make sure they look okay
- Scala Users discourse https://users.scala-lang.org
- Announce on Twitter from @scala_lang
- Announce on Mastodon from @scala_lang
- Seth has the login info for Twitter and Mastodon. Upstream contact is Toli.
- Discord: link to release notes in #links channel
- consider also saying something in #scala-contributors channel
- Unblock the release in Scala Steward by PRing an update to default.scala-steward.conf
- Add the release to SDKMAN
- as per the documentation at https://sdkman.io/vendors
- URL provided must be in
.zip
format,.tgz
doesn't work - sample command:
curl -X POST -H "Consumer-Key: xxx" -H "Consumer-Token: xxx" -H "Content-Type: application/json" -H "Accept: application/json" -d '{"candidate": "scala", "version": "2.13.9", "url": "https://downloads.lightbend.com/scala/2.13.9/scala-2.13.9.zip"}' https://vendors.sdkman.io/release
- replace both
xxx
s with the credential information provided to Seth by Marco Vermeulen (marco at sdkman dot io) - test afterwards with
sdk list scala
andsdk install scala <version>
(these should work immediately once thePOST
succeeds) - to correct mistakes,
PATCH
andDELETE
are also available - broadcast the addition via the SDKMAN twitter account
- sample command:
curl -X POST -H "Consumer-Key: xxx" -H "Consumer-Token: xxx" -H "Content-Type: application/json" -H "Accept: application/json" -d '{"candidate": "scala", "version": "2.13.9", "url": "https://github.com/scala/scala/releases/tag/v2.13.9"}' https://vendors.sdkman.io/announce/struct
- make sure it shows up at https://twitter.com/sdkman_
- sample command:
- Announce on https://reddit.com/r/scala
- ask Seth to announce on #scala IRC
Afterwards
- Scala 3: open PR updating version:
- two places to update:
project/Build.scala
community-build/community-projects/stdLib213
(after updating https://github.com/dotty-staging/scala to include recent commits)
- https://github.com/lampepfl/dotty/pulls
- two places to update:
- Scastie: open PR adding new version (modeled on scalacenter/scastie#538)
- note that the PR won't be mergeable until kind-projector has published; and if kind-projector's version number has changed,
ScalaTarget.scala
will need updating
- note that the PR won't be mergeable until kind-projector has published; and if kind-projector's version number has changed,
If it's a major release:UpdatelatestSpecVersion
inspec/_config.yml
on the old branch, so that spec is marked as no longer currentDitto for the nightly build and spec links in_data/footer.yml
and_data/doc-nav-header.yml
on docs.scala-lang.org
- (Lightbend) Fortify:
- Publish scala-fortify-plugin
- Update scala-fortify
- Update scala-fortify-docs
- (Lightbend) Notify eng-updates
- Create a scala/scala PR to:
- update
starr.version
in/versions.properties
- update
Global / baseVersion
in/build.sbt
- update
mimaReferenceVersion
in/project/MimaFilters.scala
- clear out
mimaFilters
in/project/MimaFilters.scala
, except the one(s) labeled "KEEP" spec/_config.yml
, if it's a major release
- update
- Update https://contributors.scala-lang.org thread
- Create https://contributors.scala-lang.org thread for the next release
You're done!
- Close this ticket and close the scala-dev milestone
Let's add JDK 23 to the 'community build' step?
@Philippus good point; done above and in: ed8ebfb