Skip to content

Files

Latest commit

 

History

History
295 lines (199 loc) · 12.4 KB

release.adoc

File metadata and controls

295 lines (199 loc) · 12.4 KB

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

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 /tmp/) 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

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

Camel K ships a Maven dependency containing the CRDs required in Kubernetes. This dependency is available in /java/ directory and has to be released together with Camel K. The process below is the same used for Camel K Runtime.

To prepare a release and check problems:

cd java
./mvnw release:prepare -Prelease -DautoVersionSubmodules=true -DdryRun

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

./mvnw 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):

./mvnw 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 "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

$ ./kamel install --operator-image=camelk/camel-k:$CAMEL_K_VERSION

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> <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
docker pull camelk/camel-k:$VERSION
docker tag camelk/camel-k:$VERSION apache/camel-k:$VERSION
docker push apache/camel-k:$VERSION
# 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

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.

Release notes

Release notes can be generated with:

# previous version released on same branch, e.g. 1.8.0
export PREV=a.b.c
# current version to be released, e.g. 1.8.1
export CUR=x.y.z
# Branch where both tags are present
export BRANCH=main
# Personal access Token for accessing Github API
export GITHUB_TOKEN=token
# Run the release-notes command
./script/gen_release_notes.sh $PREV $CUR $BRANCH

A release-notes.md file is generated and can be attached to the release github issue for reference.

Github release

Binary files can be now released on Github, together with release notes generated in previous step. Files need to be uploaded manually to a new Github release.

Before announcing the release, a simple test should be done to verify that everything is in place (running a "Hello World" integration after an installation done with a simple kamel install). Do a simple final test.

The release can be now announced to dev@camel.apache.org and users@camel.apache.org.

A PMC member with access to the @ApacheCamel Twitter account should announce the release on 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

lts: LTS
)

After the vote has passed, update the camel-website antora-playbook.yml content.sources section for camel-k and camel-k-runtime to use the newly released versions, replacing the previous released version.

You also need to 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.

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 using the make bundle command.

Once make bundle has been executed, you can run:

./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 main branch:

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

Commit to the main branch the tar.gz file and the updated index 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.

To do so, 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. In order to do so, please run the following:

make bump VERSION=<new-version> LAST_RELEASED_VERSION=<replace-version>
git commit -m "chore: bump next version to <new-version>"
git push upstream 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.