3. Release process

This is the procedure that should be followed for making an official JQM release.

3.1. Prerequisites

The following GitHub Secrets must be configured in the repository:

  • MAVEN_CENTRAL_USERNAME - Maven Central login

  • MAVEN_CENTRAL_PASSWORD - Maven Central password

  • GPG_PRIVATE_KEY - GPG private key in ASCII armor format

  • GPG_PASSPHRASE - GPG key passphrase

  • GPG_KEYNAME - GPG key id

  • DOCKER_USERNAME - Docker Hub username

  • DOCKER_PASSWORD - Docker Hub password

3.2. Update release notes

Add a chapter to the release notes & commit the file to master branch.

3.3. Release test

Before running the automated release, test the release artifacts locally.

Check out the branch master with git, then build the release version for testing:

mvn package -Prelease -Pbuild-frontend -DskipTests

The test package should be test-deployed in a two-node configuration to validate functionality.

3.4. Automated release

The release process is automated via GitHub Actions using the JQM Release workflow. You will be prompted to enter the release version (e.g., 3.2.1) and the next development version (e.g., 3.2.2-SNAPSHOT).

The workflow will automatically:

  • Run the full build and tests

  • Execute mvn release:prepare to create the release tag and bump versions

  • Execute mvn release:perform to build with -Prelease profile and deploy to Maven Central

  • Push the Git tags and commits to GitHub

  • Build and push Docker images to Docker Hub (with version, major version, and latest tags)

  • Create a draft GitHub release with the zip and tar.gz artifacts

3.4.1. Maven Central Repository validation

After the automated workflow completes, go to https://central.sonatype.com/ and publish the release.

3.5. Documentation

Go to jqm.rtfd.org and change the default branch to the newly created tag.

3.6. GitHub Release

The automated workflow creates a draft release on GitHub with the artifacts already uploaded.

  1. Go to the repository Releases page

  2. Edit the draft release for the new version

  3. Update the release notes body with a link to the documentation

  4. Once the documentation is live on ReadTheDocs, publish the release

Note

only publish after the documentation is up on ReadTheDocs. Creating a release sends a mail to followers, so any link to the doc would be dead otherwise.

3.7. Manual release process (deprecated)

Warning

The manual process is deprecated. Use the GitHub Actions workflow described above.

For reference, the manual release process now replaced by the automated release step was:

3.7.1. Environment

The release environment must have:

  • PGP & the release private key

  • Internet access

  • Login & password to Maven Central Repository

  • Docker client 18.06+

3.7.2. Full build & tests

There is no distinction between tests & integration tests in JQM so this will run all tests.

mvn clean install -Pbuild-frontend

3.7.3. Release

mvn release:prepare -Darguments='-DskipTests'

This creates a Git tag with the release version and updates the POMs to the next development version.

Then the test package must be test-deployed in a two-node configuration. To build the release version for testing:

mvn package -Prelease -Pbuild-frontend -DskipTests scm:checkout -Drevision=<tag-name>

This will checkout the release tag, build it, and upload to Maven Central Repository.

mvn release:perform -Darguments='-Dgpg.keyname=<keyname> -Prelease -Pbuild-frontend -DskipTests'

3.7.4. Git push

git push origin --tags
git push origin

3.7.5. Docker Hub upload

Checkout the version tag

git checkout jqm-all-3.2.0

For linux amd64 architecture, build the Docker image for the new release

docker build --platform linux/amd64 --rm --pull --provenance=false --sbom=false -t enioka/jqm:3.2.0 -f ./linux/Dockerfile ../

Push the image to Docker Hub

docker push enioka/jqm:3.2.0

Then tag the image as latest and 3 and push again

docker tag enioka/jqm:3.2.0 enioka/jqm:latest
docker tag enioka/jqm:3.2.0 enioka/jqm:3
docker push enioka/jqm:latest
docker push enioka/jqm:3

3.7.6. GitHub upload

Create a release inside GitHub and upload the zip and tar.gz produced by the jqm-service project.