Skip to content

Latest commit

 

History

History
297 lines (204 loc) · 14.3 KB

release.adoc

File metadata and controls

297 lines (204 loc) · 14.3 KB
Raw

Releasing Apache Camel K

This procedure describes all the steps required to release a new version of Apache Camel K. It is not intended to be final, but rather a working document that needs to be updated when new requirements are found or the technical process changes.

Note
 starting Camel K version 2, the release process of Kamelets catalog and Camel K Runtime is independent.

First time settings

If it’s the first time you are releasing Camel K, you may be required to follow certain configuration for gpg and maven. Just follow the instructions you can find in Camel K Runtime project about release. They contain a simplified guidelines to the more generic Camel release guide required to setup the Maven environment and gpg for the release.

Docker Hub staging setting

This project staging is hosted on CamelK Docker Hub organization. Make sure one of the organization administrator grant your personal user the right privileges to push an image to this org.

Software required to release

In order to release Camel K you may need certain software installed in the machine from where you’re performing the release action. Most of the actions are scripted and may assume the presence of tools (in some case with specific version). Here a best effort list (may not be fully accurate):

  • git CLI

  • mvn CLI

  • Docker and DockerX tooling

  • QEMU - required to emulate ARM64 build

  • cyclonedx-gomod CLI - required to generate SBOM

Verify if your machine can build an ARM64 container image

As suggested above, you may need to install some software to be able to build an ARM64 based image. You can verify that with:

docker buildx ls | grep arm
Note
 if you don’t list any available builder, if you’re on Ubuntu, you can install quickly QEMU via sudo apt-get install -y qemu qemu-user-static and retry to list the ARM64 based builders afterward.

Release Camel K

As the process will do Git operations, it is advisable that you clone the Camel K repository to some new location (ie /Desktop/) in order to avoid to conflict with any other development in progress. If you’re starting a major or a minor release version, you need to create the respective release-a.b.x branch. It’s highly advisable not to release directly from main branch.

git clone https://github.com/apache/camel-k.git /tmp/camel-k
cd /tmp/camel-k

# If you release a patch version, otherwise see next chapter
git checkout release-2.0.x
Note
 don’t use /tmp/ directories as the release process may last a few days and files generated before the voting, will be used once the release is finalized. If you use any temporary directory, make sure to store the files generated by the release procedure or later recover them from Apache dist folders.

Create release branch

Warning
 Only run this when starting a new major or minor release.

We have a script that simplify this process as we also need to provide the CI tasks required for all the supported releases.

./script/release-branch.sh
Note
 you can run the script with -d option to dry run and evaluate the changes before pushing them to the repo.

Release Camel K CRD dependency

Checkout the release branch for which you want to perform the release:

git checkout release-2.x.0

To prepare a release and check problems:

cd java/crds
mvn release:prepare -Prelease -DautoVersionSubmodules=true -DdryRun

Check the signatures of the files, then clean and prepare the actual release:

mvn release:clean release:prepare -Prelease -Duser=<your Apache LDAP id> [-Dpassword=<your Apache LDAP pwd>] -Darguments=-DskipTests -DautoVersionSubmodules=true

Then perform the release (use any settings holding your Apache credentials):

mvn release:perform -Prelease [-s path/to/your/settings.xml]

Go to https://repository.apache.org/ and close the staging repository.

A URL will be generated for the repository, like: https://repository.apache.org/content/repositories/orgapachecamel-xxxx. The URL needs to be communicated during the voting process.

Release Camel K Operator and CLI

Releasing the Camel K main artifacts require some manual steps. The following tasks need to be done:

  • Align KAMELET_CATALOG_REPO_TAG in Makefile to latest released tag of the camel-kamelets repository

  • Align DEFAULT_RUNTIME_VERSION in Makefile to latest Camel K Runtime release

  • Set the proper VERSION, likely just remove -SNAPSHOT suffix

  • Ensure LAST_RELEASED_VERSION points to latest released version of Camel K

# you probably were in /java/
cd ..
make clean codegen set-version generate check-licenses build-resources build

Commit and push the changes done so far.

git add *
git commit -m "chore(release): preparing for next release"
# assuming you're on release branch and have write permissions
git push

Now you can execute the release on staging.

make release-staging

A docker image camelk/camel-k:<version> will be pushed to the staging organization (camelk, not apache). Binary files (CLIs) will be generated as well and put in the project root directory.

Do some testing

Make sure to test the CLI you’re about to publish. Expand and test the platform and architecture according to your local environment specifications:

$ tar -xvf camel-k-client-2.0.0-linux-amd64.tar.gz
...
$ ./kamel version
Camel K Client 2.0.0

If the version retrieved is the one expected you can run an installation procedure

CUSTOM_IMAGE=camelk/camel-k CUSTOM_VERSION=$CAMEL_K_VERSION make bundle
make install-k8s-global

Make some test and if all is in order, you can upload the sources and CLIs to the dist/dev repository in ASF the staged artifacts, in order to link them in the release vote communication.

cd release-utils/scripts/
./upload-source.sh <released_version>

Check that all resources have been correctly uploaded to https://dist.apache.org/repos/dist/dev/camel/camel-k/<released_version>/ directory.

Voting

An email should be sent to dev@camel.apache.org asking to test the staged artifacts. Voting will be left open for at least 72 hours. Use any previous voting email as a template.

Finalizing the release

After the voting is complete with success, the artifacts can be released.

Republish docker image in the Apache org on Docker Hub:

# assuming logged in to docker hub (default amd64)
docker pull camelk/camel-k:$VERSION-amd64
docker tag camelk/camel-k:$VERSION-amd64 apache/camel-k:$VERSION-amd64
docker push apache/camel-k:$VERSION-amd64
# push any other supported architecture (ie, arm64)
docker pull camelk/camel-k:$VERSION-arm64
docker tag camelk/camel-k:$VERSION-arm64 apache/camel-k:$VERSION-arm64
docker push apache/camel-k:$VERSION-arm64
# create and push the manifest
docker manifest create apache/camel-k:$VERSION--amend apache/camel-k:$VERSION-amd64 --amend apache/camel-k:$VERSION-arm64
docker manifest push --purge apache/camel-k:$VERSION

Release the staging repository at: https://repository.apache.org (Camel K CRD dependency). Artifacts committed on https://dist.apache.org/repos/dist/dev/ before the voting process need to be copied to the Apache dist repository on: https://dist.apache.org/repos/dist/release/camel.

cd release-utils/scripts/
./promote-release.sh <released_version>

Wait for maven mirrors to sync the new artifacts. This can take more than 1 hour sometimes.

Github release

You can start a release from the tag created in the previous steps (ie, v2.1.0). You can use the automatic release note generator, making sure to select the previous stable release to generate the differences. You need to manually add the CLI files, the CRDs dependency and the sbom.json created in the previous steps. Select it as latest stable release and finalize the process.

Before announcing the release, perform a simple test to verify that everything is in place (running a "Hello World" integration after an installation done with, as an example kubectl apply -k github.com/apache/camel-k/install/overlays/openshift/descoped?ref=v2.1.0 --server-side). Do a simple final test.

The release can be now announced to dev@camel.apache.org and users@camel.apache.org ideally accompanied by a blog post to explain what’s new. A PMC member with access to the @ApacheCamel former Twitter account should announce the release on former Twitter as well.

Post Release

Documentation updates

The version of Camel K and the main related dependencies are scraped automatically in a Github Action. You only need to provide the LTS parameter in the related release branch, when the release is marked as LTS (such as in https://github.com/apache/camel-k/blob/f15124949e43bb859d07f555b9e510956d6ed823/docs/antora.yml#L30). You also need to make sure that the antora.yml file has correctly set the version (which may be still set as main) and the prerelease tag (which should be removed as we are officially releasing).

After the vote has passed you should update camel-website project:

  1. update the camel-website antora-playbook.yml content.sources section for camel-k to use the newly released versions, replacing the previous released version or any unsupported version.

  2. create an entry in the release section of Camel website project: https://github.com/apache/camel-website/tree/main/content/releases/k - you can use any previous document as a reference.

  3. provide a blog post announcing the release

Note
 the milestone is the github project milestone ID used to track the release.

Operator Hub

The OperatorHub downstream channel should be synced to publish the latest version of Camel K, so that it can be easily installed on platforms that support Operator Hub.

The Embedded OperatorHub in OpenShift and OKD downstream channel should be synced to publish the latest version of Camel K, so that it can be easily installed on OpenShift and OKD.

You can create the bundle and prepare the supported OLM environments:

make bundle
./script/prepare-operators.sh <version_just_released>

You’ll get two different folders in the bundle folder - k8s-operators - openshift-ecosystem

In both the directories you’ll have a folder with the version number specified in the command line.

The content of these folders is exactly what you need as base to create a PR for OperatorHub and Embedded OperatorHub in OpenShift and OKD.

Helm

An helm chart must be generated with the new version.

First update the chart version in the Chart.yaml file under the /helm section, setting a new chart release from the release branch:

./script/set_version.sh <released-version>
make release-helm

Locally commit the changes and use the commit ID to cherry pick this commit to the main branch. It should be 2 files, the tar.gz file that have been generated in /docs/charts and the updated Chart.yaml.

Note
 if you’re releasing from a release branch, then, you need to generate the Helm chart in the specific release branch, and later manually commit the chart in main branch accordingly.

Wait for them to be available on https://hub.helm.sh/.

Homebrew

The HomeBrew formula for kamel must be synced to download and build the latest version of Camel K, so it can be easily installed on macOs and Linux platforms.

Note
 it seems it exist an automatic process in charge to update Brew formula as soon as there is a release. Check it out if after the release, a pull request with the new version for kamel is automatically done.

Manual procedure

If the automatic procedure does not start, the content of kamel.rb (the package definition) should be updated to point the latest release of Camel K. This is something done using brew CLI and providing a HOMEBREW_GITHUB_API_TOKEN env variable to contain gists, repo and workflow grants [1]. Once these are set, you need to run:

brew tap homebrew/core
brew bump-formula-pr --strict kamel --version=<x.y.z>

The previous script should create a PR on behalf of your Github account with the required changes to update the formula.

Note
 be patient, it can take a little time to update the formula.

Bump to next version

Once the release process is complete, we must prepare the configuration for next version. First of all, make sure you’re on the release branch and everything is up to date. Then, use a new patch version, likely adding a unit to the patch semantic version.

git pull
make bump VERSION=<new-version>-SNAPSHOT LAST_RELEASED_VERSION=<replace-version>
git commit -a -m "chore(release): bump next version to <new-version>-SNAPSHOT"
git push origin HEAD:release-a.b.x

Where <new-version> represents the new version you want to bump and <replace-version> the version that was previously released.

If you’re releasing a minor or a major version, then, you need also to bump the main branch with the following version. It should be the same process as in the release branch, but, this time, on main and updating the minor or major semantic version.

git checkout main
git pull
make bump VERSION=<new-version>-SNAPSHOT LAST_RELEASED_VERSION=<replace-version>
git commit -a -m "chore(release): bump next version to <new-version>-SNAPSHOT"
git push origin HEAD:main

Now, the release process is completed. Thanks for taking care. Make sure to remove the local repository on your machine to avoid any further update on the project by mistake.