[WIP] update-guide

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

@@ -0,0 +1,60 @@
+////
+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
+////
+////
+TODO: See xref:{doc-guides}/doc-reference.adoc[Quarkus style and content guidelines] for details
+- Title should have an implied "How to..." in front.
+- ID should end with '-howto' (using the filename works)
+- choose appropriate categories
+////
+[id="update-projects-to-quarkus-3-howto"]
+= Update projects to Quarkus 3
+: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 an update command. This command uses OpenRewrite recipes to update most of the dependencies, source code, and documentation in your project. You must also evaluate whether your project requires additional follow-up steps.
+
+[IMPORTANT]
+====
+After the update, you must evaluate whether to perform additional update tasks.
+====
+
+:extension-status: "experimental"
+include::{includes}/extension-status.adoc[]
+
+== Prerequisites
+
+:prerequisites-time: 30 minutes
+include::{includes}/prerequisites.adoc[]
+
+== Procedure
+
+. Using your your version control system, create a working branch for your project or projects .
+. Run the xref:example-update-commands[example update command] that matches your project environment.
+. Evaluate the output from the update command and perform additional steps, if needed.
+. Review link:https://github.com/quarkusio/quarkus/wiki/Migration-Guide-3.0[the migration guide] for any items that are not covered by the upgrade command and perform additional steps, if needed.
+// IMPORTANT: As a developer considering whether to use the update command, I need to know which tasks in the migration guide are handled by the update command and which ones aren't. Otherwise, without that information, using the update command produces an unknown result and I'm more likely to perform the updates manually.
+. Review all the changes using a diff tool.
+. Verify that the project builds without errors, passes all tests, and that the application works as expected before releasing it to production.
+
+[id="example-update-commands"]
+== Example update commands
+
+.Maven and the Quarkus CLI
+[source,]
+----
+quarkus update --stream=3.0
+----
+
+== Examples
+
+Baeldung tutorials provide solid examples of How-To guides.
+For example, "How to use Jackson annotations" is answered (with variations) here: https://www.baeldung.com/jackson-annotations
+
+== References
+
+To help direct the reader to more information about the content topic, optionally add a *References* section to the end of the page and include `links` or `xrefs` to other related content resources.