Apache Camel Quarkus release process

The process is mutatis mutandis the same as for the main Apache Camel repository - see the Release guide page of the Camel documentation.

The process is oriented toward releasing the main branch, some adjustments might be needed when it come to releasing maintenance branches.

Here, just a sketch of the repeating part, after you have performed the initial setup following the Camel Release guide.

Pre release tasks

  • When releasing after a recent Quarkus release, check for new releases of third party Quarkus extensions we depend on. They are listed in the Primary dependencies section of the top level pom.xml. If there are new releases, upgrade the versions accordingly and run mvn cq:sync-versions -N from the root directory of the source tree. Note that some of the versions are mandated by quarkus, so camel-quarkus should use the same values as the quarkus-platform bom.

  • Close the GitHub release milestone and assign any remaining issues that aren’t covered by the release to the next milestone

Create a release branch

$ export VERSION=$(mvn help:evaluate -Dexpression=project.version -q -DforceStdout | sed 's|-SNAPSHOT||') # the version you are releasing, e.g. 0.1.0
$ export NEXT_VERSION=$(echo ${VERSION} | awk -F. -v OFS=. '{$NF++;print}')-SNAPSHOT # the next development iteration, e.g. 0.1.1-SNAPSHOT
$ export BRANCH=$(echo $VERSION | sed 's|.[0-9][0-9]*$|.x|') # the release branch, e.g. 0.1.x
$ git fetch upstream # upstream is git@github.com:apache/camel-quarkus.git
$ git checkout main # main is the branch from which you want to release
$ git reset --hard upstream/main # make sure you are in sync with upstream
$ git checkout -b $BRANCH

release:prepare and release:perform

With Camel Quarkus, adding -Prelease to release:prepare and release:perform is not necessary, because all necessary profiles are set in the configuration of the maven-release-plugin.

The Maven command to release is as follows:

$ mvn clean release:clean release:prepare -DreleaseVersion=$VERSION -DdevelopmentVersion=$NEXT_VERSION -B release:perform

In case release:prepare is successful but an issue occurs during release:perform, you can resume from the failing artifact to save some time:

  • First find out from the console output, in which module the release:perform task failed. Say that there was an upload timeout in camel-quarkus-openapi-java module.

  • Then locate the directory mvn release:perform used for checking out the tag and running the deploy goal. It is usually <root_of_the_project>/target/checkout:

    $ cd target/checkout
  • And finally resume the deploy build as follows:

    $ mvn deploy -Papache-release -DskipTests -Denforcer.skip -Dquarkus.build.skip -Dformatter.skip -Dimpsort.skip -Dskip.installyarn -Dskip.yarn -rf :camel-quarkus-openapi-java

Close the Apache staging repository

  • Login to the Apache staging repository using your Apache LDAP credentials.

  • Click on Staging Repositories

  • Then select org.apache.camel-quarkus-xxx in the list of repositories, where xxx represents your username and ip

  • Click Close on the toolbar above

  • This will close the repository from future deployments and make it available for others to view

  • After that, a popup window is created, enter the name and version of the artifact being released in the Description field and finally click Close

Update the Apache Camel Quarkus development subversion repository

Camel Quarkus provides some release scripts to push the required bits in development subversion repository.

$ cd release-utils/scripts/
$ ./upload-source.sh $VERSION $VERSION

This will take care of grabbing the source zip from github and getting the SBOMs from target directory. After signing the files, it will push the folder to dist/dev/

After the changes have been committed. You can check them by browsing to https://dist.apache.org/repos/dist/dev/camel/camel-quarkus/.

Collect the performance regression report

Once the staging repository has been closed, run the perf-regression tool in order to compare the current staging against the previous released version.

It’s important that the machine running the perf-regression tool be equally loaded during the run. The simplest way would be to take a 1 hour slot at the end of the day, launch the tool on your main station and then lock the screen.

At this stage, one is probably working from the release branch. The performance regression tool might be present in the target/checkout folder. Otherwise a full mvn clean install -Dquickly rebuild is needed prior to running the performance regression tool. Another option is to switch to the main branch, where no rebuild should be needed.

For instance, running the tool to compare the 2.10.0 staging release against the 2.9.0 previous release would look as below:

$ java -jar target/quarkus-app/quarkus-run.jar -an 2.9.0 2.10.0

After approximately 1 hour, it should generate a report like below:

 Camel Quarkus version  |  Duration  |   JVM req/s [%increase]   |  Native req/s [%increase]  |  Status  |
 ---------------------------------------------------------------------------------------------------------
                 2.9.0  |       10m  |  16127.95 req/s [+0.00%]  |    9421.92 req/s [+0.00%]  |      OK  |
                2.10.0  |       10m  |  15334.57 req/s [-4.92%]  |    9044.55 req/s [-4.01%]  |      OK  |

Copy/paste the generated report into issue CAMEL-QUARKUS-4012.

The perf-regression tool has some options that could come in handy if one needs to:

  • Specify the camel-quarkus staging repository url, e.g. when doing the release from a machine and checking regression from another

  • Specify the camel staging repository url, e.g. when the camel release is still under vote

  • Perform regression tests in JVM mode only, e.g. on machine where quarkus.native.container-build could not be used

  • Run longer tests, e.g. to confirm that a potential regression detected with 10 minutes long scenarios remains with 1h long scenarios

  • Run shorter tests, e.g. to have quick feedback when trying to tune the perf-regression tool options

For more details about options, please run:

$ cd tooling/perf-regression
$ java -jar target/quarkus-app/quarkus-run.jar --help

Start an upstream vote

Send a mail to start the upstream vote. There are plenty of mails on the dev mailing list to get inspiration from. For instance, one could search mail with subject below:

[VOTE] Release Camel Quarkus 3.0.0-M1

Next version in Camel Quarkus main branch

If there are no substantial commits in the release branch, which need to get merged/cherry-picked to main, you can perform this step right after creating the release branch. Otherwise, e.g. if there is a Camel upgrade in the release branch which is not available on Maven Central yet, it is better to perform this step after the new Camel release is available on the Central and after all relevant commits were merged/cherry-picked to main.

While in the release branch we set the $NEXT_VERSION to the next micro SNAPSHOT (e.g. when releasing 0.1.0, $NEXT_VERSION would be 0.1.1-SNAPSHOT), in main, we typically set the next version to the next minor SNAPSHOT (the next minor SNAPSHOT of 0.1.0 is 0.2.0-SNAPSHOT).

$ NEXT_RELEASE=... # e.g. 0.2.0
$ NEXT_SNAPSHOT="${NEXT_RELEASE}-SNAPSHOT"
$ git checkout "main"
$ git reset upstream/main
$ mvn release:update-versions -DautoVersionSubmodules=true -DdevelopmentVersion=$NEXT_SNAPSHOT -B
$ sed -i "s|<camel.quarkus.jvmSince>[^<]*</camel.quarkus.jvmSince>|<camel.quarkus.jvmSince>$NEXT_RELEASE</camel.quarkus.jvmSince>|" tooling/create-extension-templates/runtime-pom.xml
$ sed -i "s|<camel.quarkus.nativeSince>[^<]*</camel.quarkus.nativeSince>|<camel.quarkus.nativeSince>$NEXT_RELEASE</camel.quarkus.nativeSince>|" tooling/create-extension-templates/runtime-pom.xml
$ mvn cq:sync-versions -N
$ mvn clean install -Dquickly # to regen the Qute Camel component metadata + flattened boms
$ git commit -am "Next is $NEXT_SNAPSHOT"
# Send a pull request

Close the upstream vote

After 72h, the vote may need to be closed. There are plenty of mails on the dev mailing list to get inspiration from. For instance, one could search mail with subject:

[Result][VOTE] Release Apache Camel Quarkus 3.0.0-M1

Release the Apache staging repository after the vote

  • Login to the Apache staging repository using your Apache LDAP credentials.

  • Click on Staging Repositories

  • Then select org.apache.camel-quarkus-xxx in the list of repositories, where xxx represents your username and ip

  • Click Release on the toolbar above

  • This will release the repository and make artifacts generally available

  • After that, a popup window is created, click Close

Update the Apache Camel Quarkus distribution subversion repository

Once the staging repository has been released, the Apache Camel Quarkus distribution subversion repository should be updated as sketched below.

If you are doing this for the first time you need to checkout the Apache Camel Quarkus distribution subversion repository:

$ svn checkout 'https://dist.apache.org/repos/dist/release/camel' camel-releases-dist

In case you have performed the above step during some release in the past, you need to update your working copy:

$ cd camel-releases-dist
$ svn update .

Make sure your public key is present in the KEYS file. Add it, if it is not there yet using gpg command:

$ export EMAIL= # the e-mail address in your key
$ gpg -k $EMAIL >> KEYS
$ gpg --armor --export $EMAIL >> KEYS

Assemble the Apache Camel Quarkus sources distribution and SBOM artifacts:

$ mkdir -p "camel-quarkus/$VERSION"
$ cd "camel-quarkus/$VERSION"
$ export URL='https://repository.apache.org/content/repositories/releases/org/apache/camel/quarkus/camel-quarkus'
$ wget -O "apache-camel-quarkus-$VERSION-src.zip" "$URL/$VERSION/camel-quarkus-$VERSION-src.zip"
$ wget -O "apache-camel-quarkus-$VERSION-src.zip.asc" "$URL/$VERSION/camel-quarkus-$VERSION-src.zip.asc"
$ wget -O "apache-camel-quarkus-$VERSION-sbom.json" "$URL/$VERSION/camel-quarkus-$VERSION-cyclonedx.json"
$ wget -O "apache-camel-quarkus-$VERSION-sbom.json.asc" "$URL/$VERSION/camel-quarkus-$VERSION-cyclonedx.json.asc"
$ wget -O "apache-camel-quarkus-$VERSION-sbom.xml" "$URL/$VERSION/camel-quarkus-$VERSION-cyclonedx.xml"
$ wget -O "apache-camel-quarkus-$VERSION-sbom.xml.asc" "$URL/$VERSION/camel-quarkus-$VERSION-cyclonedx.xml.asc"
$ sha512sum "apache-camel-quarkus-$VERSION-src.zip" > "apache-camel-quarkus-$VERSION-src.zip.sha512"
$ sha512sum "apache-camel-quarkus-$VERSION-sbom.json" > "apache-camel-quarkus-$VERSION-sbom.json.sha512"
$ sha512sum "apache-camel-quarkus-$VERSION-sbom.xml" > "apache-camel-quarkus-$VERSION-sbom.xml.sha512"

Ensure that only the latest release from each maintained branches is present (including active LTS versions). Typically, when releasing e.g. 1.4.0, you may need to delete e.g. 1.3.0:

$ cd ..
$ ls
1.3.0 1.4.0
$ svn remove 1.3.0

Review the changes:

$ cd ..
$ svn diff

Commit the changes:

$ svn add --force .
$ svn commit -m "Apache Camel Quarkus $VERSION released artifacts"

Altenatively you could also use the release-scripts promote-release.sh

$ cd release-utils/scripts/
$ ./promote-release.sh $VERSION $VERSION

where $VERSION is the version just released.

Upgrade Camel Quarkus in Quarkus Platform

You can proceed with upgrading Camel Quarkus in Quarkus Platform once the newly released artifacts are available on Maven Central.

Synchronization between Apache Maven repository and Maven Central may take hours. You may find the await-release mojo of cq-maven-plugin handy if you need to upgrade Camel Quarkus in the Platform as soon as possible:

$ cd camel-quarkus
$ mvn cq:await-release -Dcq.version=$(git describe --tags `git rev-list --tags --max-count=1`)

The mojo first lists the artifacts having groupId org.apache.camel.quarkus and the given $VERSION from the local Maven repository and then checks that they are available in Maven Central. As long as there are unavailable artifacts, the requests are re-tried with a (configurable) delay of 60 seconds.

Quarkus Platform hosts the metadata and Maven BOMs necessary for code.quarkus.io as well as for Quarkus tools.
  • Clone Quarkus Platform unless you have done it in the past

    $ git clone git@github.com:quarkusio/quarkus-platform.git
  • Change camel-quarkus.version property in the Quarkus platform top level pom.xml to the newly released version:

    $ cd quarkus-platform
    $ export NEW_VERSION=... # the version you just released, e.g. 0.1.0
    $ sed -i "s|<camel-quarkus.version>[^<]*</camel-quarkus.version>|<camel-quarkus.version>$NEW_VERSION</camel-quarkus.version>|" pom.xml
    # Make sure that it worked
    $ git status
  • Review the list of skipped tests configured on the Camel member in pom.xml (E.g ones that have <skip>true</skip>). If any are known to have been fixed in the latest release, remove the entries so that they can be enabled again.

  • Re-generate the BOMs

    $ ./mvnw clean install -DskipTests
    # ^ This will take a couple of minutes because it resolves
    # every single dependency of every single extension included
    # in the platform
    #
    # double check files are well formatted
    $ ./mvnw -Dsync
    
    
    # Then commit the generated changes
    $ git add -A
    $ git commit -m "Upgrade to Camel Quarkus $NEW_VERSION"
  • Run Camel Quarkus integration tests at least in JVM mode:

    cd generated-platform-project/quarkus-camel/integration-tests
    mvn clean test
  • If all tests are passing, send a pull request to the Platform. If there are some new features, fixes, etc. in the release that would be worth to mention in the upcoming Quarkus announcement, you can tag the pull request with release/noteworthy-feature label and provide a short text about those features in the PR description.

Create a GitHub release

This will trigger sending a notification to folks watching the Camel Quarkus github repository, so it should ideally happen once the newly released artifacts are available on Maven Central.

The following needs to be done:

  • Go to https://github.com/apache/camel-quarkus/releases.

  • Click the tag you want to promote to a GitHub release

  • Click "Create release from tag" button

  • In the "New release" form:

  • Leave "Release title" empty

  • Choose the tag of the previous release from the "Previous tag" select field

  • Click the "Generate release notes" button. It should generate a summary all changes for the release.

  • In addition you can add links to blog posts if required. e.g. something like

    Check the full [release announcement](https://camel.apache.org/blog/2021/06/camel-quarkus-release-2.0.0/)
  • Click the green "Publish release" button at the bottom

Update the project changelog

In the Camel Quarkus main branch, create a new release heading in the CHANGELOG.md file. E.g ## 3.2.0. Under there, you can copy & paste the generated release notes markdown (see previous step) from the GitHub release page into CHANGELOG.md.

You may also want to clean up the markdown, for instance:

  • Remove any excess sections like the What’s Changed heading

  • Fix up any abbreviated lines that end in …​

Upgrade and tag Examples

This section needs to be executed only when a Quarkus Platform release has been published. It should be the case most of the time. In this case, right after the newest Quarkus Platform becomes available on Maven Central:

  • Make sure all PRs against camel-quarkus-main branch are merged.

  • Since Camel Quarkus 2.3.0, the examples should use Quarkus Platform BOMs in the main branch. To set it do the following:

    $ NEW_PLATFORM_VERSION=... # E.g. 2.2.0.Final
    $ git fetch upstream
    $ git checkout camel-quarkus-main
    $ git reset --hard upstream/camel-quarkus-main
    $ mvn org.l2x6.cq:cq-maven-plugin:2.10.0:examples-set-platform -Dcq.quarkus.platform.version=$NEW_PLATFORM_VERSION
    $ git add -A
    $ git commit -m "Upgrade to Quarkus Platform $NEW_PLATFORM_VERSION"
  • Make sure that the tests are still passing:

    $ ./mvnw-for-each.sh clean verify -Pnative
  • If everything works for you locally, open a PR to merge camel-quarkus-main to main

  • Once the PR is merged, tag the main branch with the $NEW_CQ_VERSION:

    $ NEW_CQ_VERSION=... # the recent release of Camel Quarkus; e.g. 2.2.0
    $ git checkout main
    $ git fetch upstream
    $ git reset --hard upstream/main
    $ ./mvnw-for-each.sh versions:set -DnewVersion=$NEW_CQ_VERSION
    # Update version labels in Kubernetes resources
    $ ./mvnw-for-each.sh process-sources
    $ git add -A
    $ git commit -m "Tag $NEW_CQ_VERSION"
    $ git tag $NEW_CQ_VERSION
    $ git push upstream main
    $ git push upstream $NEW_CQ_VERSION
    # Create a maintenance branch for the release unless this is a micro release
    $ export BRANCH=$(echo $NEW_CQ_VERSION | sed 's|.[0-9][0-9]*$|.x|')
    $ git checkout -b $BRANCH $NEW_CQ_VERSION
    $ git push upstream $BRANCH
  • Prepare the camel-quarkus-main branch for the next development iteration:

    $ NEXT_CQ_VERSION=... # The version used in the current Camel Quarkus main branch without the -SNAPSHOT suffix; e.g. 2.3.0
    $ git checkout camel-quarkus-main
    $ git reset --hard main
    $ ./mvnw org.l2x6.cq:cq-maven-plugin:2.10.0:examples-set-platform -Dcq.camel-quarkus.version=${NEXT_CQ_VERSION}-SNAPSHOT -Dcq.newVersion=${NEXT_CQ_VERSION}-SNAPSHOT
    # Update version labels in Kubernetes resources
    $ ./mvnw-for-each.sh process-sources
    $ git add -A
    $ git commit -m "Next is $NEXT_CQ_VERSION"
    $ git push upstream camel-quarkus-main --force-with-lease

Write the release announcement blog post

Taking inspiration from previous release announcement blog post, we need to write one for the release at hand.

Please, keep in mind a few things when preparing the pull request for the camel-website:

Further steps

In addition to the above, the following is needed: