release.adoc - camel-k - Git at Google

 = 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.

 [[releasing-settings]]
 == 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 https://github.com/apache/camel-k-runtime[Camel K Runtime project] about release. They contain a simplified guidelines to the more generic https://github.com/apache/camel/blob/main/docs/user-manual/modules/ROOT/pages/release-guide.adoc[Camel release guide] required to setup the Maven environment and gpg for the release.

 === Docker Hub staging setting

 This project staging is hosted on https://hub.docker.com/orgs/camelk/repositories[CamelK Docker Hub organization]. Make sure one of the organization administrator grant your personal user the right priviledges to push an image to this org.

 [[releasing-camel-k]]
 == 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. Consider if you're about to release from `main` branch (generally a new major or minor version) or from a `release` branch (when you're about to release a patch version). In the latter case, you need to checkout to the proper release branch, ie `git checkout release-1.12.x`.

 [[releasing-camel-k-crds]]
 === 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 togheter 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 -Prelease
 ./mvnw release:prepare -Prelease -Duser=<your Apache LDAP id> [-Dpassword=<your Apache LDAP pwd>] -Darguments=-DskipTests -DautoVersionSubmodules=true
 ```

 Then perform the release:

 ```
 ./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]]
 === Release Camel K Operator and CLI

 Releasing the Camel K main artifacts require some manual steps.

 First thing is to checkout main branch and sync with upstream.

 Next, the version of the runtime libraries to use need to be aligned in the Makefile.

 The following tasks need to be done:

 - Align `KAMELET_CATALOG_REPO_TAG` in Makefile to latest released tag of the camel-kamelets repository
 - Align `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

 ```
 make clean codegen set-version build-resources check-licenses
 ```

 Rebuild auto-generated data, including trait info:

 ```
 make generate clean build-resources build
 ```

 Commit and push the changes done so far.

 ```
 git add *
 git commit -m "preparing for next release"
 # assuming write permissions
 git push upstream <branch_name>
 ```

 Now the release on staging can be executed.

 ```
 make release-staging
 ```

 Binary files will be generated and put in the project root directory, including examples.

 Now run:

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

 This will upload the sources, client and examples to the dist/dev repository in ASF.

 A docker image `camelk/camel-k:<version>` will be pushed to the staging organization (`camelk`, not `apache`).

 [[testing]]
 == Do some testing

 A combined release can be immediately tested with the following install command:

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

 [[release-notes]]
 == 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.

 [[documentation]]
 == 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)

 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.

 [[voting]]
 == 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.

 [[finalizing]]
 == 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
 ```

 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.

 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.

 Download section on the website needs to be put in sync to display the new release.
 Checkout the website and put an entry under `content/releases/k` with the version of the new release (copy the last release as template).
 The milestone field in the release doc is the Github id for the milestone (e.g. for v1.4.1, the milestone is 22).

 [[post-release]]
 == Post Release

 === Operator Hub

 The https://github.com/k8s-operatorhub/community-operators/[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 https://github.com/redhat-openshift-ecosystem/community-operators-prod/[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 https://github.com/k8s-operatorhub/community-operators/[OperatorHub] and https://github.com/redhat-openshift-ecosystem/community-operators-prod/[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`.

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

 === Homebrew

 The https://brew.sh/[HomeBrew] formula for _kamel_ must be synced to download and build the latest version of https://github.com/apache/camel-k[Camel K], so it can be easily installed on _macOs_ and _Linux_ platforms.

 To do so, the content of https://github.com/Homebrew/homebrew-core/blob/master/Formula/kamel.rb[homebrew-core/Formula/kamel.rb] _(the package definition)_ should be updated to point the latest release of https://github.com/apache/camel-k[Camel K].

 More importantly the _tag_ and _revision_ section configuration should change for a new release e.g
 ```
   url "https://github.com/apache/camel-k.git",
     :tag      => "0.3.4",
     :revision => "c47fb2c85e89852f0fd111d1662f57917030ced5"
   head "https://github.com/apache/camel-k.git"
 ```

 _P.S please note that the bottles are created using the https://docs.brew.sh/Brew-Test-Bot[Brew Test Bot]   https://docs.brew.sh/Bottles[ [1] ]._

 === 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 main
 ```
 Where <new-version> represents the new version you want to bump and <replace-version> the version that was previously released.

 Note: this action should also replace automatically the oldest nightly release Github Action with the newest one just created.

 You will also need to update the `docs/antora.yml` configuration in order to provide the proper versions for the upcoming release in `main` branch.
	= 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.

	[[releasing-settings]]
	== 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 https://github.com/apache/camel-k-runtime[Camel K Runtime project] about release. They contain a simplified guidelines to the more generic https://github.com/apache/camel/blob/main/docs/user-manual/modules/ROOT/pages/release-guide.adoc[Camel release guide] required to setup the Maven environment and gpg for the release.

	=== Docker Hub staging setting

	This project staging is hosted on https://hub.docker.com/orgs/camelk/repositories[CamelK Docker Hub organization]. Make sure one of the organization administrator grant your personal user the right priviledges to push an image to this org.

	[[releasing-camel-k]]
	== 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. Consider if you're about to release from `main` branch (generally a new major or minor version) or from a `release` branch (when you're about to release a patch version). In the latter case, you need to checkout to the proper release branch, ie `git checkout release-1.12.x`.

	[[releasing-camel-k-crds]]
	=== 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 togheter 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 -Prelease
	./mvnw release:prepare -Prelease -Duser=<your Apache LDAP id> [-Dpassword=<your Apache LDAP pwd>] -Darguments=-DskipTests -DautoVersionSubmodules=true
	```

	Then perform the release:

	```
	./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]]
	=== Release Camel K Operator and CLI

	Releasing the Camel K main artifacts require some manual steps.

	First thing is to checkout main branch and sync with upstream.

	Next, the version of the runtime libraries to use need to be aligned in the Makefile.

	The following tasks need to be done:

	- Align `KAMELET_CATALOG_REPO_TAG` in Makefile to latest released tag of the camel-kamelets repository
	- Align `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

	```
	make clean codegen set-version build-resources check-licenses
	```

	Rebuild auto-generated data, including trait info:

	```
	make generate clean build-resources build
	```

	Commit and push the changes done so far.

	```
	git add *
	git commit -m "preparing for next release"
	# assuming write permissions
	git push upstream <branch_name>
	```

	Now the release on staging can be executed.

	```
	make release-staging
	```

	Binary files will be generated and put in the project root directory, including examples.

	Now run:

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

	This will upload the sources, client and examples to the dist/dev repository in ASF.

	A docker image `camelk/camel-k:<version>` will be pushed to the staging organization (`camelk`, not `apache`).

	[[testing]]
	== Do some testing

	A combined release can be immediately tested with the following install command:

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

	[[release-notes]]
	== 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.

	[[documentation]]
	== 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)

	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.

	[[voting]]
	== 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.

	[[finalizing]]
	== 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
	```

	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.

	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.

	Download section on the website needs to be put in sync to display the new release.
	Checkout the website and put an entry under `content/releases/k` with the version of the new release (copy the last release as template).
	The milestone field in the release doc is the Github id for the milestone (e.g. for v1.4.1, the milestone is 22).

	[[post-release]]
	== Post Release

	=== Operator Hub

	The https://github.com/k8s-operatorhub/community-operators/[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 https://github.com/redhat-openshift-ecosystem/community-operators-prod/[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 https://github.com/k8s-operatorhub/community-operators/[OperatorHub] and https://github.com/redhat-openshift-ecosystem/community-operators-prod/[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`.

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

	=== Homebrew

	The https://brew.sh/[HomeBrew] formula for _kamel_ must be synced to download and build the latest version of https://github.com/apache/camel-k[Camel K], so it can be easily installed on _macOs_ and _Linux_ platforms.

	To do so, the content of https://github.com/Homebrew/homebrew-core/blob/master/Formula/kamel.rb[homebrew-core/Formula/kamel.rb] _(the package definition)_ should be updated to point the latest release of https://github.com/apache/camel-k[Camel K].

	More importantly the _tag_ and _revision_ section configuration should change for a new release e.g
	```
	url "https://github.com/apache/camel-k.git",
	:tag => "0.3.4",
	:revision => "c47fb2c85e89852f0fd111d1662f57917030ced5"
	head "https://github.com/apache/camel-k.git"
	```

	_P.S please note that the bottles are created using the https://docs.brew.sh/Brew-Test-Bot[Brew Test Bot] https://docs.brew.sh/Bottles[ [1] ]._

	=== 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 main
	```
	Where <new-version> represents the new version you want to bump and <replace-version> the version that was previously released.

	Note: this action should also replace automatically the oldest nightly release Github Action with the newest one just created.

	You will also need to update the `docs/antora.yml` configuration in order to provide the proper versions for the upcoming release in `main` branch.