Update your projects to Quarkus 3 by using the Quarkus CLI

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

@@ -0,0 +1,89 @@
+////
+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-howto"]
+= Update projects to Quarkus 3 automatically
+:extension-status: preview
+include::_attributes.adoc[]
+:categories: core
+:summary: Update projects from Quarkus 2.13 and later to Quarkus 3.
+
+As a developer, you can update your projects from Quarkus 2.13 and later to Quarkus 3 by running one of the update commands.
+These commands use OpenRewrite recipes to automatically update most of your project's dependencies, source code, and documentation.
+
+//  For existing applications where all extensions are available, we have an OpenRewrite recipe you can try. GIVE LINK
+//
+// Once this has been run, your project should update its dependencies, source code, and documentation to use Quarkus 3.
+//
+// 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.
+====
+
+:extension-status: "experimental"
+include::{includes}/extension-status.adoc[]
+
+== Prerequisites
+
+:prerequisites-time: 30 minutes
+include::{includes}/prerequisites.adoc[]
+
+== Procedure
+
+. 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.
+. link:https://quarkus.io/guides/cli-tooling#installing-the-cli[Install Quarkus CLI version 3 or later].
+. Use your version control system to create a working branch for your project or projects.
+. 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="example-update-commands"]
+== Alternatives to using the Quarkus CLI
+
+Instead of using the Quarkus CLI, you can use Maven or JBang to update your project to Quarkus 3.x.
+
+.Maven
+
+[source,bash]
+----
+./mvnw io.quarkus.platform:quarkus-maven-plugin:3.0.0.CR2: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"
+----