Creating Releases and Snapshots

This page documents the WALA release process and availability of WALA snapshot builds. It is mostly relevant to those who are hacking on WALA itself.

Snapshots

On Sonatype

WALA's GitHub Actions configuration is set up to upload a new snapshot build to Sonatype on each successful commit to master. You can see the snapshot builds here. As is usual, the version naming scheme is X.X.X-SNAPSHOT.

Installing local snapshots

If you have local changes to WALA, you can install them as a snapshot build into your local Maven repository with the following command:

./gradlew publishToMavenLocal

You can then import this snapshot build from other repositories. For Gradle, you can use the local Maven repository by writing:

repositories {
    mavenLocal()
}

You may need to put mavenLocal before other repositories while you are testing the local snapshot builds, as snapshots are also present on Maven Central.

Publishing released versions locally

Note: The paragraph below applies only to releases 1.5.9 and earlier; these issues are fixed for subsequent releases, so that release versions can be published locally with ./gradlew publishToMavenLocal just like for snapshot builds.

You may want to publish a released (non-snapshot) version of WALA to your local Maven repository, e.g., because WALA's test fixture artifacts do not get published to Maven Central alongside other release artifacts. However, running ./gradlew publishToMavenLocal for a release version requires signing the artifacts. To avoid this signing step, run ./gradlew publishLocalPublicationToMavenLocal instead (this command also works for snapshot versions). See the discussion here for more details.

Releases

Here are the steps for pushing a new WALA release to Maven Central.

Initial Setup

General documentation on using Maven Central is here:

http://central.sonatype.org/pages/ossrh-guide.html

You'll need to have Sonatype credentials and to have permission to push releases for the WALA namespace.

GPG key setup documentation is here:

http://central.sonatype.org/pages/working-with-pgp-signatures.html

WALA uses the Gradle Signing Plugin to sign artifacts. To be able to sign artifacts, set up your ~/.gradle/gradle.properties file with the following properties:

SONATYPE_NEXUS_USERNAME=xxxxxxxxxx
SONATYPE_NEXUS_PASSWORD=xxxxxxxxxxxxxx
signing.keyId=xxxxxxxxxxxxxx
signing.password=xxxxxxxxxxxxxx
signing.secretKeyRingFile=/Users/me/.gnupg/secring.gpg

The signing.keyId property should be the ID of the public key you will use to sign the artifacts; run gpg2 --list-keys to find the ID of your public key. With gpg 2.1 or greater you may need to export your secret keys to secring.gpg; see details here.

Tagging and uploading a release

Important: Before starting the release process, be sure that the latest WALA master is green on CI. Otherwise, you may ship a broken release. Also, make sure others are not pushing to master during the process. All the steps below should occur with the latest master branch checked out. Finally, run java -version and make sure you are running a JDK 11 virtual machine, to ensure the released jars are JDK 11 compatible.

During development, WALA master uses a SNAPSHOT release version corresponding to the next release (e.g., 1.3.8-SNAPSHOT). When all other changes for the release are committed, the first step for tagging a release is to update this version number to a non-SNAPSHOT version by modifying the VERSION_NAME property in the gradle.properties file in the top-level directory:

VERSION_NAME=X.Y.Z

Once this is done, commit the changes:

git commit -am "Prepare for release X.Y.Z."

Then, tag the release:

git tag -a vX.Y.Z -m "Version X.Y.Z"

Upload the release files to the staging area for Maven Central:

./gradlew --no-parallel --no-configuration-cache clean publishAllPublicationsToMavenRepository

This step may take several minutes. Also, it will sign the archives, so if you don't have gpg set up correctly, it will fail. The --no-parallel flag is important, to prevent parallel uploads of artifacts, which doesn't work.

Then, modify gradle.properties again to update the version to the next snapshot, e.g.:

VERSION_NAME=X.Y.Q-SNAPSHOT

Commit the change:

git commit -am "Prepare next development version."

Push to master (you will need to temporarily disable the branch protection to do this):

git push && git push --tags

At this point, it is ok for others to push to master.

Completing the release on Sonatype

Log in to Sonatype Nexus with your Sonatype credentials. Then, click "Staging Repositories" on the left. Scrolling down the list, you should eventually see something like "comibmwala_xxxx", where xxxx is a number. Select that repo, and click "Close" at the top of the list. After this step completes successfully, click "Release" at the top of the repository. After that completes, the staging repo should be dropped and no longer appear on the list. After some further delay (usually minutes, possibly hours), the artifacts will become available on Maven Central.