Migration to Quarkus 3

Co-authored-by: Guillaume Smet <[email protected]>

Author: mkouba

_posts/2023-05-20-quarkus-3-upgrade.adoc

@@ -0,0 +1,97 @@
+---
+layout: post
+title: 'Migration to Quarkus 3.0 is a breeze'
+date: 2023-05-25
+tags: migration
+synopsis: 'Quarkus 3 is out and we encourage our users to upgrade their applications to experience the best Quarkus ever!'
+author: mkouba
+---
+
+Quarkus 3 is out and we encourage our users to upgrade their applications to experience the best Quarkus ever!
+The team worked hard to deliver a lot of new features and performance improvements.
+But of course, there are also some breaking changes.
+The https://github.com/quarkusio/quarkus/wiki/Migration-Guide-3.0[migration guide] describes all the important changes in the core extensions.
+
+Nevertheless, there is also some tedious work that needs to be done.
+Quarkus 3 has updated to the latest Jakarta EE 10 APIs, which include the infamous change of the `javax.\*` to the `jakarta.*` packages.
+If your application makes use of any Jakarta API, and there's a good chance it does (think about JAX-RS, CDI, JPA, etc.), you'll need to modify your code.
+Furthermore, if there's an explicit Jakarta API dependency in the project, you'll need to update this dependency as well.
+
+Of course, you can migrate the application manually.
+But since Quarkus embraces the developer joy there is the Quarkus Update Tool to the rescue!
+
+== Quarkus Update Tool - TL;DR
+
+. Install the https://quarkus.io/guides/cli-tooling[Quarkus CLI] or make sure a 3+ version is installed
+. Run `quarkus update --stream=3.0`
+. Check the changes made by the tool
+. Profit!
+
+== Quarkus Update Tool - The Full Story
+
+The goal of the update tool is to help developers to migrate an application to Quarkus 3 smoothly.
+The update process can be triggered from the Quarkus CLI, and directly via Maven or Gradle commands.
+The tool itself is basically a set of https://docs.openrewrite.org/[OpenRewrite transformation rules].
+Most of the rules are defined in the https://github.com/quarkusio/quarkus-updates[Quarkus Update Recipes] project.
+
+What exacty does the update tool do?
+
+* Updates the Quarkus version
+* Transforms the source code to use the `jakarta.*` packages
+* Upgrades the Quarkiverse extensions to the versions compatible with Quarkus 3.0
+* Updates the Java EE API dependencies to the Jakarta EE API versions
+* Adjusts some common dependencies (such as Jackson and Hibernate)
+* Transforms the configuration files for some configuration properties (for example `quarkus.kubernetes.host` to `quarkus.kubernetes.ingress.host`)
+* Renames some common service providers (for example `/META-INF/services/javax.ws.rs.ext.Providers` to `/META-INF/services/jakarta.ws.rs.ext.Providers`)
+
+TIP: Maven multi-module projects with standard layout are also supported if the parent project imports a Quarkus Platform BOM.
+
+Let's get down to business.
+To run the update:
+
+[source,role="primary asciidoc-tabs-target-sync-cli"]
+.CLI
+----
+quarkus update --stream=3.0
+----
+
+[source,role="secondary asciidoc-tabs-target-sync-maven"]
+.Maven
+----
+./mvnw io.quarkus.platform:quarkus-maven-plugin:3.0.3.Final:update -N -Dstream=3.0
+----
+
+[source,role="secondary asciidoc-tabs-target-sync-gradle"]
+.Gradle
+----
+./gradlew -PquarkusPluginVersion=3.0.3.Final quarkusUpdate --stream=3.0
+----
+
+IMPORTANT: If using https://quarkus.io/guides/cli-tooling[Quarkus CLI] then always make sure the latest version is used. The `quarkus version` command should output version 3+.
+
+Keep in mind that there is no dry-run mode.
+In other words, once you trigger the update, the changes will be immediately written to the file system.
+However, you can leverage the source code management tool to see the transformations applied.
+For example, if using Git then run the update tool and execute the `git diff` command afterwards to see the changes. 
+And if something went wrong then just use `git checkout .` to revert the changes.
+
+TIP: If your application depends on Hibernate ORM, the dedicated https://github.com/quarkusio/quarkus/wiki/Migration-Guide-3.0:-Hibernate-ORM-5-to-6-migration[Hibernate ORM 5 to 6] migration guide will come in handy.
+
+That's it.
+Your application should be ready now.
+If there's something wrong please, ping us on Zulip or file a https://github.com/quarkusio/quarkus/issues[new issue].
+
+== Summary
+
+In this article, we discussed the possibilities of the Quarkus Update Tool that will make your migration to Quarkus 3.0 a breeze.
+Don't hesitate and go for it!
+
+NOTE: The Quarkus Update Tool is not a one-time thing. The plan is to use this tool to provide easy updates for the future versions of Quarkus as well.
+
+== More resources
+
+- https://github.com/quarkusio/quarkus/wiki/Migration-Guide-3.0[Migration Guide 3.0]
+- https://github.com/quarkusio/quarkus/wiki/Migration-Guide-3.0:-Hibernate-ORM-5-to-6-migration[Migration Guide 3.0 - Hibernate ORM 5 to 6]
+- https://github.com/quarkusio/quarkus-updates[Quarkus Update Recipes]
+- https://quarkus.io/guides/cli-tooling[Quarkus CLI]
+