- General: Releasing repositories by tag
- Play Core Repository Release Procedure
- Before the release
- Release tracking issue
- Intro
- Prerequisites
- If something goes wrong
- Releasing Play
- sbt-web plugins release procedure
As of 2022 all repository in the Play Framework GitHub organization are released by tag...
This is released from the main
branch from 2.9.0
forward. Unless an older version needs patching, then it must be released from the maintenance branch, for instance 2.8.x
branch. If there is no maintenance branch for the release that needs patching, create it from the tag.
- Check the draft release notes to see if everything is there
- Wait until the main build finished after merging the last PR
- Update the draft release with the next tag version (eg.
2.9.0
), title and release description - Check that GitHub Actions release build has executed successfully (GitHub will start a CI build for the new tag and publish artifacts to Sonatype)
- Go to Staging repository and release the concrete staging repository
- The artifacts will become visible at https://repo1.maven.org/maven2/com/typesafe/play/
See if there are issues that need triage and are possibly related to the upcoming release. This is mainly important if you are doing a minor or major release.
Create a new release tracking issue.
When cutting a release of Play, you need to make the following decision:
- Does this release of Play require releasing the modules that depend on it, e.g. play-grpc and play-slick. For a typical minor release, it would not. For a major release, and often for pre releases of major releases, the answer is yes.
As of 2022 all repositories in the Play Framework organization are released by tag. That means the sonatype credentials are set up at the GitHub organization level.
To release from older branches however you might still have to release from your machine, that's why you have to set up the sonatype credentials locally.
See here how that is done (either by setting credentials +=...
or using the env variable).
The release process pushes all artifacts to maven central and "promote" them automatically.
If the build fails during or after the promotion of maven central artifacts, there is no going back. Published artifacts are immutable, they find their way into CDNs, into caches on developer machines, and if there are two different versions of the same artifact out there, this can cause big problems. Your only option is to fix the problem, and attempt another release of the next version. Remember, version numbers are cheap.
If the build failed during or before the publishing of artifacts, but not after maven central promotion, you can drop the maven central staging repository.
This can either be done through their corresponding web interfaces, or by using the sonatypeDrop
sbt commands.
The most common failure is a request timeout. Typically, you can see in the logs that all artifacts have been uploaded and the build fails with a timeout while closing the repository or promoting it. If that's the case, the easiest solution is to close and promote by hand on Sonatype.
Check when was the last time scala-steward ran on the repository and consider updating the dependencies yourself. Have a look in the .scala-steward.conf.
Take this with a grain of salt. It's good and nice to have a release with the latest dependencies, but dependency updates at the last minute can come with surprises.
Prepare the branch for each project:
- Look for PRs that should be merged.
- Look at
status:needs-backport
issues/PRs (including closed ones). - Look at issues/PRs tagged milestone version (including closed ones).
- Update any dependencies that are needed.
- Update any upstream projects (e.g make sure new
play-ws
is using newplay-json
)
May need to release these projects: play-json
, play-ws
, twirl
When ready:
- If the project already has set up
sbt-ci-release
:- Make sure you are on the latest HEAD of the branch you want to release
- Tag the version you want to release:
git tag -s x.y.z
- Push the tag to the upstream repo.
- In the GitHub user interface, check "Publish" action, it will publish the release.
- If you release from an older branch that has no
sbt-ci-release
set up yet:- Make sure you are using JDK8 to build and release!
- Checkout the branch you want to release and check that the commit you want to release has a green build in CI
- Tag the commit, eg: (
git tag -s x.y.z
). The projects are usingsbt-dynver
, so tagging first is important in order to get the right version number. The projects are NOT using tag prefixes (eg: v1.0.2), they use 1.0.2 instead. Watch-out, don't be mislid by twirl and play-ws. They do have tags prefixed by av
, but the dynver config is requiring the new tags to NOT have a prefix. - Run
sbt release
- At the end of the release, you must push the tag.
- Check the correcponding release page in GitHub, adapt the release notes as needed and published it.
Prepare the branch:
- Look for PRs that should be merged.
- Look at
status:needs-backport
issues/PRs (including closed ones). If you are releasing an older version of Play, look at thestatus:needs-backport-x.x
label too. - Look at issues/PRs tagged milestone version (including closed ones).
- Updated any dependencies that are needed (e.g. Dependencies.scala).
- Do a local build or the appropriate snapshot and use the
local-test.sh
fromplay-samples
for a final round of tests.
When ready:
- If releasing 2.9 or newer:
- Tag the version you want to release:
git tag -s x.y.z
- Push the tag to the upstream repo.
- In the GitHub user interface, check "Publish" action, it will publish the release.
- Tag the version you want to release:
- If releasing from
2.8.x
:- Make sure you are using JDK8 to build and release.
- Ccheckout the branch you want to release and check that the commit you want to release has a green build in CI
- Tag the commit, eg: (
git tag -s x.y.z
). The projects are using sbt-dynver, so tagging first is important in order to get the right version number. Play is NOT using tag prefixes (eg: v1.0.2), it uses 1.0.2 instead and dynver is configured as such. - Run
sbt -J-XX:ReservedCodeCacheSize=512m release
- At the end of the release, you must push the tag.
- Check the corresponding release page in GitHub, adapt the release notes as needed and published it.
Once Play is released, you need to wait 10 minutes or so for a Maven central sync before you can perform any of the remaining tasks.
Verification:
You can check that the artifacts are available at Maven Central under play_<scalaversion>
.
You can see the staged artifacts here on OSS Sonatype. E.g. here is a search for Play 2.8.18 artifacts.
Warning: After pushing the a tag to GitHub, a GitHub actions workflow will be trigger.
This includes the modules:
- play-slick
- play-ebean
- scalatestplus-play
- play-grpc
Only release these if they need to be released, generally for minor Play releases, there's no reason to cut a new release of these, these libraries are free to have their own release cycle.
Note: since we update omnidoc and the Play templates and seeds people reading the docs or starting a new project will automatically see and use the latest minor versions of all modules, even if we don't patch all modules directly to update dependencies.
You may need to bump the Play version in the external module, do this, commit, and depending on how major the version bump is, push directly to the repo or go through a pull request. Once that is done, to release:
For play-slick
and scalatestplus-play
:
- Make sure you are using JDK8 to build and release
- Checkout the branch you want to release and check that the commit you want to release has a green build in CI
- Tag the commit, eg: (
git tag -s x.y.z
). The projects are using sbt-dynver, so tagging first is important is important in order to get the right version number. The projects are NOT using tag prefixes (eg: v1.0.2), they use 1.0.2 instead. - Run
sbt release
- At the end of the release, you must push the tag.
- Check the correcponding release page in GitHub, adapt the release notes as needed and published it.
TODO: all of the above should soon become obsolete. All that process should be run by the CI build.
Again, you will need to wait 10 minutes or so for a Maven central sync before you can perform any of the remaining tasks. In the meantime you can see the staged artifacts here on OSS Sonatype. E.g. here is a search for Play 2.8.18 artifacts: https://oss.sonatype.org/#nexus-search;gav~com.typesafe.play~~2.8.18~~
Verification:
You can check that the artifacts are available at Maven Central under <library>_<scalaversion>
or <sbt-plugin>_2.12_1.0
:
- https://repo1.maven.org/maven2/com/typesafe/play/
- https://repo1.maven.org/maven2/org/scalatestplus/play/
Verification: when you run sbt new playframework/play-{scala,java}-seed.g8 it should pick up the new version on Maven. Try the templates out. You may need to update them if they don't work with the new version of Play.
Warning: This is a compulsory step and the version X.Y.Z of omnidoc released here must match the version X.Y.Z of Play released in step 1 above.
Omnidoc builds Play's documentation from all the current versions of Play and its modules. To understand what omnidoc really does under the covers, read the README. Note that once omnidoc completed, you will have the docs on the machine where you run the command and you still need to push them to play-generated-docs
(next step).
In the omnidoc build file for the branch of Play that you are releasing:
- Update the Play version to the version of Play that you just released, and also
- Update any external modules to their latest version that is compatible with that version of Play.
Here's an example update to the omnidoc 2.8.x branch.
$ git diff
diff --git a/project/OmnidocBuild.scala b/project/OmnidocBuild.scala
- val playVersion = sys.props.getOrElse("play.version", "2.8.0")
+ val playVersion = sys.props.getOrElse("play.version", "2.8.1")
Push this changes directly to GitHub (no need for a pull request).
To tag omnidoc:
- For Play 2.9 we do not need to publish artifacts anymore:
- Just create a tag by using
git tag -s
or the GitHub UI. Make sure you are on the correct branch (where you just set the correct versions described above) - After the tag was pushed, there will be NO GitHub actions ci workflow run anymore because we do not need to publish artifacts.
- Now locally: Make sure you checked out the tag you just created, make sure the working directoy is clean, so
sbt version
display the version nice (without-SNAPSHOT
etc.) - Run
sbt +publishLocal
- Continue with the play generated docs step below.
- Just create a tag by using
- For Play 2.8.x you still have to release by hand and actually publish artifacts:
- make sure you are using JDK8 to build and release
- checkout the branch you want to release and check that the commit you want to release has a green build in CI
- DO NOT create a tag. Omnidoc does not have a
version.sbt
file and also does not use sbt-dynver. It gets its version from Play. - run
sbt release
- at the end of the release, the commit will be tagged and you must push the tag.
- Verification: check that the artifacts are available at Maven Central under
play-omnidoc_<scalaversion>
. It may take a few minutes. https://repo1.maven.org/maven2/com/typesafe/play/
Once that is done, you can update the docs on playframework.com, by running:
Checkout https://github.com/playframework/play-generated-docs and switch to the branch you are releasing.
In play-generated-docs
checkout and after switching the branch, eg: 2.8.x, run the following:
rm -rf api/java
rm -rf api/scala
rm -rf manual
rm -rf confs
Followed by...
cp -r <path-to-omnidoc>/target/scala-2.13/omnidoc/javadoc api/java
cp -r <path-to-omnidoc>/target/scala-2.13/omnidoc/scaladoc api/scala
cp -r <path-to-omnidoc>/target/scala-2.13/omnidoc/playdoc/manual manual
cp -r <path-to-omnidoc>/target/scala-2.13/omnidoc/playdoc/confs confs
Where <path-to-omnidoc>
is the path to the omnidoc repo in your machine that you just released.
In play-generated-docs
git add --all
git commit -m "Documentation for <tag>"
git push origin <branch>
git tag -sm "Version <tag>" <tag>
git push origin <tag>
Where <tag>
is the version you are releasing, eg: 2.8.11 and branch is the branch you are updating eg: 2.8.x
Verification: check there is a new tag <tag>
at https://github.com/playframework/play-generated-docs project. It
should be on top of https://github.com/playframework/play-generated-docs/releases. The website should pick this
tagged version of the generated docs up to 10 minutes later. You can check that then using the following URL
pattern: https://www.playframework.com/documentation/<tag>/Home
. For example
https://www.playframework.com/documentation/2.7.2/Home.
Update the Play version (and other released artifacts) in any of the play-example projects.
Verification: The sample repository builds can be seen at https://github.com/playframework/play-samples/actions/workflows/build-test.yml. Make sure the build is green and then merge the pull request. Only continue the release procedure if the samples pass the test! If they don't it's an indicator the relase might break existing applications!
These are the steps to update https://playframework.com website.
If you are releasing a MAJOR version, review the contents of .version
in play-generated-docs
before updating the site.
Update playReleases.json
and changelog.md
in playframework.com website git repository.
Note that the changelog should be updated describing all milestone/release candidates for the same release
collectively. In addition the playReleases.json
should be updated with the development releases in place i.e.
you don't need to publish information on both an M1 and an M2 release. If the release is for the latest stable
or development version, upgrade the website itself to use that version.
Commit and push your changes.
NOTE: you will need a distinct SSH public key for this. Talk to Matthias or someone from the steering committee if you don't have access.
To set up your public key:
- Ask someone else from Play team to give you access the Play secrets.
- Download the PEM file and log into the machine:
ssh -i PlayProd2015.pem [email protected]
cd playframework.com
git pull
sbt stage
- Restart the linux service:
sudo systemctl restart playframework.service
Verification: Check that https://www.playframework.com/changelog contains the new release and also if the previous release moved to https://www.playframework.com/releases.
- If the release contains security fixes post an update on https://groups.google.com/g/play-framework-security
- Publish the release on https://github.com/playframework/playframework/releases. There should be a release draft already.
- Make sure to check
[x] Create a discussion for this release
before publishing the release!
- Make sure to check
- Tweet about the new release: https://twitter.com/playframework/
- Post in the LinkedIn group: https://www.linkedin.com/groups/3818467/
- Post an (email) update on the Play Open Collective page: https://opencollective.com/playframework#category-CONNECT
- Post an (email) update in the GitHub Sponsors Dashboard https://github.com/sponsors/playframework/dashboard/updates (private link)
- Post on Scala Reddit https://www.reddit.com/r/scala/
Tip: This shouldn't be necessary anymore because release drafter already adds all the author itself to the release notes, which will the display nicely at the bottom of a release. In case you want to list all the authors that contributed to a release you can use:
git fetch --tags && git shortlog -s 2.8.0..2.8.1 | cut -c8- | sort
Verification:
- https://github.com/playframework/playframework/discussions/categories/announcements - check the announcement!
- https://twitter.com/playframework - check the tweet!
- Close the milestone for the release you just made
- Create a new milestone for the next release
- Move issues and pull requests from the old milestone to the new one if necessary
You'll need the write access to the sbt-web plugin's Github repo.
The easiest way to do this is to be added to the sbt-web team: https://github.com/orgs/sbt/teams/sbt-web.
You can then see all the repos you can publish to (with the playframework
sonatype user): https://github.com/orgs/sbt/teams/sbt-web/repositories
In addtion the playframework
sonatype user can also publish releases for https://github.com/sbt/sbt-eclipse.
You have to join the sbteclipse
team for that: https://github.com/orgs/sbt/teams/sbteclipse
- You'll need to set up a PGP key so that sbt release can sign the artifacts. Signing is done with sbt-pgp. Read the docs there if you need more info.
- Run
sbt release
- Answer all prompts with defaults - you'll need to provide your PGP passphrase too
- After publish has finished update the project's
README.md
to show the latest version. You can do this with Github's online editor and push it.