Update your projects to Quarkus 3 by using the Quarkus CLI

docs/src/main/asciidoc/update-to-quarkus-3.adoc

@@ -0,0 +1,98 @@
+////
+This document is maintained in the main Quarkus repository, and pull requests should be submitted there:
+https://github.com/quarkusio/quarkus/tree/main/docs/src/main/asciidoc
+////
+[id="update-projects-to-quarkus-3-automatically-howto"]
+= Update projects to Quarkus 3 automatically
+include::_attributes.adoc[]
+:categories: core
+:extension-status: "experimental"
+
+Update projects from Quarkus 2.13 and later to Quarkus 3.
+
+include::{includes}/extension-status.adoc[]
+
+== Introduction
+
+As a developer, you can update your projects from Quarkus 2.13 and later to Quarkus 3 by running an update command.
+The update command uses OpenRewrite recipes to automatically update most of your project's dependencies, source code, and documentation.
+
+// Give the link to the OpenRewrite recipe?
+// How does the user know what the update command does or does not cover?
+// In the migration guide, can we identify which items are/are not covered by the OpenRewrite recipe?
+// Do we want to invite feedback? For example: If it does not work for you, we could have missed something, or you are using extensions not yet supporting Quarkus 3.
+// https://github.com/quarkusio/quarkus/issues[Let us know] in either case so we can improve the migration script together.
+
+
+[IMPORTANT]
+====
+After updating, evaluate whether your project requires additional follow-up steps.
+Verify that the application from your updated project works as expected before releasing it to production.
+====
+
+== Prerequisites
+
+:prerequisites-time: 30 minutes
+include::{includes}/prerequisites.adoc[]
+
+[IMPORTANT]
+====
+If your project uses Hibernate ORM or Hibernate Reactive, see the link:https://github.com/quarkusio/quarkus/wiki/Migration-Guide-3.0:-Hibernate-ORM-5-to-6-migration[Hibernate ORM 5 to 6 migration] quick reference.
+====
+
+== Procedure
+
+. Use your version control system to create a working branch for your project or projects.
+. link:https://quarkus.io/guides/cli-tooling#installing-the-cli[Install Quarkus CLI version 3 or later].
++
+[NOTE]
+====
+If you choose not to install Quarkus CLI version 3, you can update your project by using Maven or JBang commands in the xref:alternative-commands[Alternative commands] section.
+====
+. Update the project using the Quarkus CLI:
++
+[source,bash]
+----
+quarkus update --stream=3.0
+----
+. Review the output from the `quarkus update` command for potential instructions and, if needed, perform the indicated tasks.
+. Review all the changes using a diff tool.
+. Review link:https://github.com/quarkusio/quarkus/wiki/Migration-Guide-3.0[the migration guide] for any items not covered by the upgrade command and perform additional steps, if needed.
+// IMPORTANT: As a developer deciding whether to use the update command, knowing which tasks the update command handles makes it more likely that I'll use this feature. Otherwise, I might avoid it.
+. Verify that the project builds without errors and that the application passes all tests and works as expected before releasing it to production.
+
+[id="alternative-commands"]
+== Alternative commands
+
+Instead of using the Quarkus CLI, you can use Maven or JBang to update your project to Quarkus 3.
+
+.Maven
+
+[source,bash]
+----
+./mvnw io.quarkus.platform:quarkus-maven-plugin:3.0.0.Final:update -N -Dstream=3.0
+----
+
+// .Gradle
+//
+//I will update and uncomment this section if/when this capability becomes available.
+
+.JBang
+
+If you have JBang installed, update your project:
+[source,bash]
+----
+jbang --fresh upgrade-to-quarkus3@quarkusio
+----
+
+For Linux and macOS, if you don't have JBang installed, install JBang and update your project:
+[source,bash]
+----
+curl -Ls https://sh.jbang.dev | bash -s - --fresh upgrade-to-quarkus3@quarkusio
+----
+
+For Microsoft Windows, if you don't have JBang installed, install JBang and update the project:
+[source,bash]
+----
+iex "& { $(iwr https://ps.jbang.dev) } --fresh upgrade-to-quarkus3@quarkusio"
+----