[camel-quarkus] branch main updated: Document how users can upgrade to new Camel Quarkus releases without a Quarkus Platform release

[pp...@apache.org]

This is an automated email from the ASF dual-hosted git repository.

ppalaga pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/camel-quarkus.git


The following commit(s) were added to refs/heads/main by this push:
     new 5389e6a47b Document how users can upgrade to new Camel Quarkus releases without a Quarkus Platform release
5389e6a47b is described below

commit 5389e6a47ba784b05e06233fc6354851f4a15754
Author: James Netherton <ja...@gmail.com>
AuthorDate: Thu Oct 26 07:57:59 2023 +0100

    Document how users can upgrade to new Camel Quarkus releases without a Quarkus Platform release
    
    Fixes #5449
---
 docs/antora.yml                                    |  1 +
 .../pages/user-guide/dependency-management.adoc    | 58 ++++++++++++++++++++--
 tooling/scripts/update-antora-config.groovy        |  2 +
 3 files changed, 57 insertions(+), 4 deletions(-)

diff --git a/docs/antora.yml b/docs/antora.yml
index adfe0b55ae..c0b95a6d40 100644
--- a/docs/antora.yml
+++ b/docs/antora.yml
@@ -30,6 +30,7 @@ asciidoc:
     # Project versions
     camel-version: 4.1.0 # replace ${camel.version}
     camel-docs-version: 4.0.x
+    camel-quarkus-version: 3.6.0 # replace ${camel-quarkus.version}
     quarkus-version: 3.5.0 # replace ${quarkus.version}
     graalvm-version: 23.0.1 # replace ${graalvm.version}
     graalvm-docs-version: jdk17
diff --git a/docs/modules/ROOT/pages/user-guide/dependency-management.adoc b/docs/modules/ROOT/pages/user-guide/dependency-management.adoc
index 9070167bef..84f03ae479 100644
--- a/docs/modules/ROOT/pages/user-guide/dependency-management.adoc
+++ b/docs/modules/ROOT/pages/user-guide/dependency-management.adoc
@@ -83,14 +83,64 @@ Note that not all combinations of artifacts managed by the various BOMs are test
 
 == Combining with other BOMs
 
-When combining `camel-quarkus-bom` with any other BOM,
+When combining `quarkus-camel-bom` with any other BOM,
 think carefully in which order you import them,
 because the order of imports defines the precedence.
 
-I.e. if `my-foo-bom` is imported before `camel-quarkus-bom` then the versions defined in
+I.e. if `my-foo-bom` is imported before `quarkus-camel-bom` then the versions defined in
 `my-foo-bom` will take the precedence.
-This might or might not be what you want, depending on whether there are any overlaps between `my-foo-bom` and `camel-quarkus-bom`
-and depending on whether those versions with higher precedence work with the rest of the artifacts managed in `camel-quarkus-bom`.
+This might or might not be what you want, depending on whether there are any overlaps between `my-foo-bom` and `quarkus-camel-bom`
+and depending on whether those versions with higher precedence work with the rest of the artifacts managed in `quarkus-camel-bom`.
+
+== Upgrading to new Camel Quarkus releases
+
+Assuming you are importing `quarkus-bom` and `quarkus-camel-bom` in your project, upgrading to new releases should be a simple case of incrementing the `quarkus.platform.version` property.
+
+Sometimes it happens that the latest Camel Quarkus release is not yet availble via the `quarkus-camel-bom`.
+To work around this, you can replace the `io.quarkus.platform:quarkus-camel-bom` import with `org.apache.camel.quarkus:camel-quarkus-bom`.
+
+Note that if you do this, some dependencies in `camel-quarkus-bom` may not be perfectly aligned with other Quarkus universe members as they would be in `quarkus-camel-bom`.
+
+[source,xml,subs="attributes+"]
+----
+<project>
+  ...
+  <properties>
+    <quarkus.platform.version>{quarkus-version}</quarkus.platform.version>
+    <camel-quarkus.version>{camel-quarkus-version}</camel-quarkus.version>
+    ...
+  </properties>
+  <dependencyManagement>
+    <dependencies>
+      <!-- The BOMs managing the dependency versions -->
+      <dependency>
+        <groupId>io.quarkus.platform</groupId>
+        <artifactId>quarkus-bom</artifactId>
+        <version>${quarkus.platform.version}</version>
+        <type>pom</type>
+        <scope>import</scope>
+      </dependency>
+      <dependency>
+        <groupId>org.apache.camel.quarkus</groupId>
+        <artifactId>camel-quarkus-bom</artifactId>
+        <version>${camel-quarkus.version}</version>
+        <type>pom</type>
+        <scope>import</scope>
+      </dependency>
+    </dependencies>
+  </dependencyManagement>
+</project>
+----
+
+IMPORTANT: Ensure that the major.minor version parts of `quarkus.platform.version` & `camel-quarkus.version` match. Mixing different release streams will likely result in build or runtime errors.
+
+When upgrading from one major release to another (E.g from 2.x to 3.x).
+Quarkus provides an https://quarkus.io/guides/update-quarkus[updater tool] that can apply the necessary modifications to your project and make it compatible with the new major release.
+
+In addition, Camel & Camel Quarkus publish migration guides that document potential breaking changes.
+
+* xref:manual::migration-and-upgrade.adoc[Camel migration guides]
+* xref:migration-guide/index.adoc[Camel Quarkus migration guides]
 
 == What's next?
 
diff --git a/tooling/scripts/update-antora-config.groovy b/tooling/scripts/update-antora-config.groovy
index 126f83bbe3..4d3459df84 100644
--- a/tooling/scripts/update-antora-config.groovy
+++ b/tooling/scripts/update-antora-config.groovy
@@ -41,6 +41,8 @@ if (!missingFiles.isEmpty()) {
 }
 
 
+project.properties['camel-quarkus.version'] = project.version.replace("-SNAPSHOT", "")
+
 final Pattern replacementPattern = ~'([\\-\\:]) *([^ ]+) *# * replace \\$\\{([^}]+)\\}'
 
 replaceInFiles.each { path ->