Create update guide

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

@@ -0,0 +1,53 @@
+////
+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"
+:summary: Update projects from Quarkus 2.13 and later to Quarkus 3.
+
+include::{includes}/extension-status.adoc[]
+
+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.
+The update command and recipes cover many but not all the items described in the link:https://github.com/quarkusio/quarkus/wiki/Migration-Guide-3.0[Migration Guide 3.0]
+If running the update command does not make all the updates you expect, the recipe might not does not cover an item in your project, or your project might be using an extension that does not support Quarkus 3 yet.
+In either case, https://github.com/quarkusio/quarkus/issues[let us know by filing an issue] so we can improve the update recipe.
+
+[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.
+In particular, if your project uses Hibernate ORM or Hibernate Reactive, read through 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.
+The following update command does not cover a significant number of the items mentioned in this Hibernate the quick reference.
+====
+
+== Prerequisites
+
+:prerequisites-time: 30 minutes
+include::{includes}/prerequisites.adoc[]
+
+== Procedure
+
+. Use your version control system to create a working branch for your project or projects.
+. Optional: To use the Quarkus CLI in the next step, link:https://quarkus.io/guides/cli-tooling#installing-the-cli[you must install version 3 of the Quarkus CLI]. You cannot use version 2 of the Quarkus 2 CLI.
+. Update the project:
++
+[source, bash, subs=attributes+, role="primary asciidoc-tabs-sync-cli"]
+.CLI
+----
+quarkus update --stream=3.0
+----
++
+[source, bash, subs=attributes+, role="secondary asciidoc-tabs-sync-maven"]
+.Maven
+----
+./mvnw io.quarkus.platform:quarkus-maven-plugin:{quarkus-version}:update -N -Dstream=3.0
+----
+. Review the output from the 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.
+. Verify that the project builds without errors and that the application passes all tests and works as expected before releasing it to production.