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 <jamesnether...@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 ->