docs/user-manual/modules/ROOT/pages/release-guide.adoc

= Release Guide

This guide covers how to create and announce a Camel release.
Instructions on updating the website to include the new documentation version are xref:release-guide-website.adoc[here].

[[ReleaseGuide-Prequisites]]
== Prequisites

To prepare or perform a release, you *must be* at least an Apache Camel committer.

* The artifacts for each and every release must be *signed*.
* Your public key must be added to the KEYS file.
* Your public key should also be cross-signed by other Apache committers (this can be done at key signing parties at
ApacheCon, for instance).
* Make sure you have the correct maven configuration in `~/.m2/settings.xml`.
* https://github.com/takari/maven-wrapper[Maven Wrapper] is used and bundled with Camel 2.21 onwards and should be used
for building the release.
* You may want to get familiar with the release settings in the parent Apache POM.
* Make sure you are using Java 11 for Apache Camel 3 and Java 21 for Apache Camel 4.

[[ReleaseGuide-MavenSetup]]
== Maven Setup
Before you deploy anything to the https://repository.apache.org[Apache Nexus repository] using Maven, you should
configure your `~/.m2/settings.xml` file so that the file permissions of the deployed artifacts are group-writable.
If you do not do this, other developers will not be able to overwrite your SNAPSHOT releases with newer versions.

The settings follow the guidelines used by the Maven project. Please pay particular attention to the
http://maven.apache.org/guides/mini/guide-encryption.html[password encryption recommendations].

[source,xml]
----
<settings>
  ...
  <servers>
    <!-- Per http://maven.apache.org/developers/committer-settings.html -->

    <!-- To publish a snapshot of some part of Maven -->
    <server>
      <id>apache.snapshots.https</id>
      <username> <!-- YOUR APACHE LDAP USERNAME --> </username>
      <password> <!-- YOUR APACHE LDAP PASSWORD --> </password>
    </server>
    <!-- To publish a website of some part of Maven -->
    <server>
      <id>apache.website</id>
      <username> <!-- YOUR APACHE LDAP USERNAME --> </username>
      <filePermissions>664</filePermissions>
      <directoryPermissions>775</directoryPermissions>
    </server>
    <!-- To stage a release of some part of Maven -->
    <server>
      <id>apache.releases.https</id>
      <username> <!-- YOUR APACHE LDAP USERNAME --> </username>
      <password> <!-- YOUR APACHE LDAP PASSWORD --> </password>
    </server>
    <!-- To stage a website of some part of Maven -->
    <server>
      <id>stagingSite</id> <!-- must match hard-coded repository identifier in site:stage-deploy -->
      <username> <!-- YOUR APACHE LDAP USERNAME --> </username>
      <filePermissions>664</filePermissions>
      <directoryPermissions>775</directoryPermissions>
    </server>

  </servers>
  ...
  <profiles>
    <profile>
      <id>release</id>
      <properties>
        <gpg.useagent>false</gpg.useagent>
        <gpg.passphrase><!-- YOUR GPG PASSPHRASE --></gpg.passphrase>
        <test>false</test>
      </properties>
    </profile>

  </profiles>
...
</settings>
----

[[ReleaseGuide-CreatingTheRelease-Camel]]
== Creating the Release

Complete the following steps to create a new Camel release:

. Grab the latest source from Git, checkout the target branch (`BRANCH_NAME`) to build from, and create a release branch off of that branch:

  
  $ git clone https://git-wip-us.apache.org/repos/asf/camel.git
  $ cd camel
  $ git checkout BRANCH_NAME
  $ git checkout -b release/NEW-VERSION

. Perform a license check with http://creadur.apache.org/rat/apache-rat-plugin[Apache Rat]:

  
  ./mvnw -e org.apache.rat:apache-rat-plugin:check
  grep -e ' !?????' target/rat.txt
  

*  The latter command will provide a list of all files without valid license headers.
  Ideally this list is empty, otherwise fix the issues by adding valid license headers and rerun the above commands before
  proceeding with the next step.

. Do a release dry run to check for problems:

  
  ./mvnw release:prepare -DdryRun -Prelease
  

* The release plugin will prompt for a release version, an SCM tag and the next release version.

*  Use a three digit release version of the form: `MAJOR.MINOR.PATCH`, e.g. `3.0.0`.

*  For the tag use a string of the form: `camel-MAJOR.MINOR.PATCH`, e.g. `camel-3.0.0`.

*  For the next version increase the patch version and append `-SNAPSHOT`, e.g. `3.0.1-SNAPSHOT`.

* Make sure to check the generated signature files:

  
  $ gpg camel-core/target/camel-core-3.0.0-SNAPSHOT.jar.asc
  gpg: assuming signed data in `camel-core/target/camel-core-3.0.0.jar'
  gpg: Signature made Sat 06 Apr 2019 03:58:01 AM PDT using RSA key ID 5942C049
  gpg: Good signature from "Gregor Zurowski <gzurowski@apache.org>"
 

. Prepare the release:

* First clean up the dry run results:


  $ ./mvnw release:clean -Prelease


* Next prepare the release:


  $ ./mvnw release:prepare -Prelease


*  This command will create the tag and update all pom files with the given version number.

. Perform the release and publish to the Apache staging repository:


  $ ./mvnw release:perform -Prelease


. Close the Apache staging repository:

* Login to https://repository.apache.org using your Apache LDAP credentials.
Click on "Staging Repositories". Then select "org.apache.camel-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.
If you are staging multiple releases together, skip this step until you have staged everything.
Enter the name and version of the artifact being released in the "Description" field and then click "Close".
This will make it easier to identify it later.

. Verify staged artifacts:

* If you click on your repository, a tree view will appear below.
You can then browse the contents to ensure the artifacts are as you expect them.
Pay particular attention to the existence of *.asc (signature) files.
If you don't like the content of the repository, right-click your repository and choose "Drop".
You can then roll back your release and repeat the process.
Note the repository URL, you will need this in your vote email.

[[ReleaseGuide-CreatingTheRelease-Camel-spring-boot]]
== Creating the Release for camel-spring-boot

Complete the following steps to create a new Camel-spring-boot release:

. Grab the latest source from Git and checkout the target branch (`BRANCH_NAME`) to build from:

  $ git clone https://git-wip-us.apache.org/repos/asf/camel-spring-boot.git
  $ cd camel
  $ git checkout BRANCH_NAME

. From Camel 3.3.0 ahead, the camel-spring-boot project uses camel-dependencies as parent.
You'll need to set the version here https://github.com/apache/camel-spring-boot/blob/master/pom.xml#L26
To the version released from the main Camel repository as the first step.
  
. Perform a license check with http://creadur.apache.org/rat/apache-rat-plugin[Apache Rat]:

  ./mvnw -e org.apache.rat:apache-rat-plugin:check
  grep -e ' !?????' target/rat.txt
  
*  The latter command will provide a list of all files without valid license headers.
  Ideally this list is empty, otherwise fix the issues by adding valid license headers and rerun the above commands before
  proceeding with the next step.

. You already have built the main camel repo for releasing, so you already have a final version in your local repository.
Change the camel-version property in https://github.com/apache/camel-spring-boot/blob/master/pom.xml accordingly and commit.

. Do a release dry run to check for problems:

  ./mvnw release:prepare -DdryRun -Prelease
  
 * The release plugin will prompt for a release version, an SCM tag and the next release version.

*  Use a three digit release version of the form: `MAJOR.MINOR.PATCH`, e.g. `3.0.0`.

*  For the tag use a string of the form: `camel-MAJOR.MINOR.PATCH`, e.g. `camel-3.0.0`.

*  For the next version increase the patch version and append `-SNAPSHOT`, e.g. `3.0.1-SNAPSHOT`.

* Make sure to check the generated signature files:

  $ gpg core/camel-spring-boot/target/camel-spring-boot-3.0.0-SNAPSHOT.jar.asc
  gpg: assuming signed data in `core/camel-spring-boot/target/camel-spring-boot-3.0.0-SNAPSHOT.jar'
  gpg: Signature made Sat 06 Apr 2019 03:58:01 AM PDT using RSA key ID 5942C049
  gpg: Good signature from "Gregor Zurowski <gzurowski@apache.org>"
 
. Prepare the release:

* First clean up the dry run results:

  $ ./mvnw release:clean -Prelease

* Next prepare the release:

  $ ./mvnw release:prepare -Prelease

*  This command will create the tag and update all pom files with the given version number.

. Perform the release and publish to the Apache staging repository:

  $ ./mvnw release:perform -Prelease

. Close the Apache staging repository:

* Login to https://repository.apache.org using your Apache LDAP credentials.
Click on "Staging Repositories". Then select "org.apache.camel-xxx" in the list of repositories, where xxx represents
your username and ip.
Click "Close" on the tool bar above.
This will close the repository from future deployments and make it available for others to view.
If you are staging multiple releases together, skip this step until you have staged everything.
Enter the name and version of the artifact being released in the "Description" field and then click "Close".
This will make it easier to identify it later.

. Verify staged artifacts:

* If you click on your repository, a tree view will appear below.
You can then browse the contents to ensure the artifacts are as you expect them.
Pay particular attention to the existence of *.asc (signature) files.
If you don't like the content of the repository, right-click your repository and choose "Drop".
You can then roll back your release and repeat the process.
Note the repository URL, you will need this in your vote email.

. Once the release has been voted

* Login to https://repository.apache.org using your Apache LDAP credentials.
Click on "Staging Repositories". Then select "org.apache.camel-xxx" in the list of repositories, where xxx represents
your username and ip.
Click "Release" on the tool bar above.
This will release the artifacts.

[[ReleaseGuide-PublishingTheRelease-Camel]]
== Publishing the Release

. Once the release has been voted:

* Login to https://repository.apache.org using your Apache LDAP credentials.
Click on "Staging Repositories". Then select "org.apache.camel-xxx" in the list of repositories, where xxx represents
your username and IP.
Click "Release" on the tool bar above.
This will release the artifacts.

. Perform a release in JIRA:

* Release the version in JIRA: https://issues.apache.org/jira/plugins/servlet/project-config/CAMEL/versions

. Copy distribution to Apache website:

  cd ${CAMEL_ROOT_DIR}/etc/scripts
  ./release-distro.sh <Camel version>
  
. Copy SBOMs to Apache website:

  cd ${CAMEL_ROOT_DIR}/etc/scripts
  ./release-sbom.sh <Camel version>

. Remove the old distribution version from the Apache website:

  svn rm https://dist.apache.org/repos/dist/release/camel/apache-camel/OLD_CAMEL_VERSION -m "Removed the old release"

. Upload the new schema files (and the manual):

  cd ${CAMEL_ROOT_DIR}/etc/scripts
  ./release-website.sh <Camel version>

. Merge the release branch back into the corresponding base branch (e.g., merge `release/3.2.0` into `camel-3.2.x`)

  git checkout BASE_BRANCH
  git pull
  git merge --no-ff release/VERSION
  git push

. Delete the local and remote release branch:

  git branch -D release/VERSION
  git push origin --delete release/VERSION

[[Publish-xsd-schemas]]
== Publish xsd schemas

* On https://github.com/apache/camel-website/tree/main/static/schema the xsd related to cxf,spring-security and spring
must be pushed to make them available to end users.

[[Tagging-examples]]
== Tagging examples

These steps are optional, and they could be done later too.

Once the release train (camel and camel-spring-boot) has been voted and published, there are some additional steps needed for the camel examples.

. Camel-examples

* On https://github.com/apache/camel-examples in the examples/pom.xml file, the following steps are necessary:

* Update the camel-dependencies version to the version coming from the release-train

* Update the `camel.version` properties to the version coming from the release-train

* To be sure everything is fine, run:

  $ ./mvnw clean install

* Commit

  $ git commit -a
  $ git push origin master (or the branch related to the release, eg. camel-3.4.x)
  $ git tag -a camel-examples-$version -m "$version"
  $ git push origin camel-examples-$version

* Now we pushed the tag, and we need to advance the version of the examples

* Update the camel-dependencies version to the next version

* Update the `camel.version` properties to the next version

* Run the following command to advance the version in the examples
  
  $ find . -type f -exec sed -i 's/$oldVersion/$newVersion/g' {} +

* To be sure everything is fine, run:

  $ ./mvnw clean install

. Camel-spring-boot-examples

* On https://github.com/apache/camel-spring-boot-examples in the examples/pom.xml file the following steps are necessary:

* Update the camel-dependencies version to the version coming from the release-train
    
* Update the `camel.version` properties to the version coming from the release-train
    
* To be sure everything is fine, run:
      
  $ ./mvnw clean install
    
* Commit
  
  $ git commit -a
  $ git push origin master (or the branch related to the release, eg. camel-3.4.x)
  $ git tag -a camel-spring-boot-examples-$version -m "$version"
  $ git push origin camel-spring-boot-examples-$version

* Now we pushed the tag, and we need to advance the version of the examples

* Update the camel-dependencies version to the next version

* Update the `camel.version` properties to the next version

* Run the following command to advance the version in the examples

  $ find . -type f -exec sed -i 's/$oldVersion/$newVersion/g' {} +
   
* To be sure everything is fine, run:

  $ ./mvnw clean install