Merge pull request #19530 from aloubyansky/docs-refer-to-new-platform…

…-coords

Update the guides to refer to the io.quarkus.platform BOMs instead of the universe BOM

docs/src/main/asciidoc/building-my-first-extension.adoc

@@ -767,25 +767,15 @@ That's why there is the Quarkus Platform.
 
 *Quarkus Platform*
 
-Quarkus proposes a `quarkus-universe-bom` which is a certified list of extensions placed under the Quarkus Platform label. From an application developer, the objectives of the platform are:
-
-* To guarantee a supportability of the extension (bugfix, security issues, dependency upgrades)
-* To ease the extension discovery through the Quarkus CLI or https://code.quarkus.io/
-* To ensure a global consistency of the extension ecosystem
-
-[TIP]
-.Should I publish my extension to the platform?
-If you feel your extensions is for you or a limited group, simply publishing to Maven is fine.
-If the extension solves a general problem, it is very handy for Quarkus users to see it on https://code.quarkus.io.
-But this comes with some responsibility for you, keeping it up to date with Quarkus minor releases (every month or so at the moment).
-When in doubt, have a conversation with the community in the https://groups.google.com/forum/#!forum/quarkus-dev[Quarkus Google Group]. We can make a collective decision.
-
-If you want to contribute a new extension, we strongly suggest you to host it in the Quarkiverse Hub.
+Quarkus platform is a set of extensions that target the primary use-cases of Quarkus as a development framework and can safely be used in any combination in the same application without creating a dependency conflict.
+From an application developer perspective, a Quarkus platform is represented as one or more Maven BOMs, for example `io.quarkus.platform:quarkus-bom:{quarkus-version}`, `io.quarkus.platform:quarkus-kogito-bom:{quarkus-version}`, etc, whose dependency version constraints were globally aligned so that these BOMs can be imported in the same application in any order without introducing a dependency conflict.
 
 *Quarkiverse Hub*
 
 link:https://github.com/quarkiverse[Quarkiverse Hub] is the GitHub organization that provides repository hosting (including build, CI and release publishing setup) for Quarkus extension projects contributed by the community.
 
+In case you are wondering about creating a new Quarkus extension and adding it to the Quarkus ecosystem so that the Quarkus community can discover it using the Quarkus dev tools (including the https://quarkus.io/guides/cli-tooling[Quarkus CLI] and https://code.quarkus.io[code.quarkus.io]), the https://github.com/quarkiverse[Quarkiverse Hub] GitHub organization will be a good home for it.
+
 You can get started by creating an link:https://github.com/quarkusio/quarkus/issues/new/choose[Extension Request] issue (check first if one wasn't already submitted link:https://github.com/quarkusio/quarkus/labels/kind%2Fextension-proposal[here]) and asking to lead it.
 
 We'll take care of provisioning a new repository and set it up to:
@@ -795,6 +785,8 @@ We'll take care of provisioning a new repository and set it up to:
 - Configure your extension to use the link:https://github.com/quarkusio/quarkus-ecosystem-ci#quarkus-ecosystem-ci[Quarkus Ecosystem CI] to build against the latest Quarkus Core changes;
 - Give you the freedom to manage the project and release to Maven Central as you like.
 
+NOTE: Extensions hosted in the Quarkiverse Hub may or may not end up in the Quarkus platform.
+
 For more information, check link:https://github.com/quarkiverse/quarkiverse/wiki[the Quarkiverse Wiki] and link:https://quarkus.io/blog/quarkiverse/[this blog post].
 
 == Conclusion

docs/src/main/asciidoc/cli-tooling.adoc

@@ -177,7 +177,7 @@ A https://quarkus.io/guides/platform#quarkus-platform-bom[Quarkus Platform relea
 +
 For example:
 +
-- Given the `2.0.0.Final` version of the CLI, specifying `-P :quarkus-universe-bom:` is equivalent to `-P io.quarkus:quarkus-universe-bom:2.0.0.Final`.
+- Given the `2.0.0.Final` version of the CLI, specifying `-P :quarkus-bom:` is equivalent to `-P io.quarkus.platform:quarkus-bom:2.0.0.Final`.
 - Specifying `-P 999-SNAPSHOT` is equivalent to `-P io.quarkus:quarkus-bom:999-SNAPSHOT`
 +
 Note: default values are subject to change. Using the `--dry-run` option will show you the computed value.

docs/src/main/asciidoc/getting-started.adoc

@@ -119,8 +119,8 @@ In addition, you can see the `quarkus-maven-plugin` responsible of the packaging
 <dependencyManagement>
     <dependencies>
         <dependency>
-            <groupId>io.quarkus</groupId>
-            <artifactId>quarkus-universe-bom</artifactId>
+            <groupId>${quarkus.platform.group-id}</groupId>
+            <artifactId>quarkus-bom</artifactId>
             <version>${quarkus.platform.version}</version>
             <type>pom</type>
             <scope>import</scope>
@@ -131,7 +131,7 @@ In addition, you can see the `quarkus-maven-plugin` responsible of the packaging
 <build>
     <plugins>
         <plugin>
-            <groupId>io.quarkus</groupId>
+            <groupId>${quarkus.platform.group-id}</groupId>
             <artifactId>quarkus-maven-plugin</artifactId>
             <version>${quarkus-plugin.version}</version>
             <extensions>true</extensions>

docs/src/main/asciidoc/maven-tooling.adoc

@@ -45,15 +45,15 @@ The following table lists the attributes you can pass to the `create` command:
 | The version of the created project
 
 | `platformGroupId`
-| `io.quarkus`
-| The group id of the target platform. Given that all the existing platforms are coming from `io.quarkus` this one won't practically be used explicitly. But it's still an option.
+| `io.quarkus.platform`
+| The group id of the target platform.
 
 | `platformArtifactId`
-| `quarkus-universe-bom`
-| The artifact id of the target platform BOM. It should be `quarkus-bom` in order to use the locally built Quarkus.
+| `quarkus-bom`
+| The artifact id of the target platform BOM.
 
 | `platformVersion`
-| If it's not specified, the latest one will be resolved.
+| The version currently recommended by the https://quarkus.io/guides/extension-registry-user[Quarkus Extension Registry]
 | The version of the platform you want the project to use. It can also accept a version range, in which case the latest from the specified range will be used.
 
 | `className`
@@ -70,7 +70,7 @@ The following table lists the attributes you can pass to the `create` command:
 
 |===
 
-By default, the command will target the latest version of `quarkus-universe-bom` (unless specific coordinates have been specified). If you run offline however, it will look for the latest locally available and if `quarkus-universe-bom` (satisfying the default version range which is currently up to 2.0) is not available locally, it will fallback to the bundled platform based on `quarkus-bom` (the version will match the version of the plugin).
+By default, the command will target the `io.quarkus.platform:quarkus-bom:{quarkus-version}` platform release (unless the coordinates of the desired platform release have been specified).
 
 If you decide to generate a REST resource (using the `className` attribute), the endpoint is exposed at: `http://localhost:8080/$path`.
 If you use the default `path`, the URL is: http://localhost:8080/hello.
@@ -425,8 +425,8 @@ If you have not used <<project-creation,project scaffolding>>, add the following
 <dependencyManagement>
     <dependencies>
         <dependency> <1>
-            <groupId>io.quarkus</groupId>
-            <artifactId>quarkus-universe-bom</artifactId>
+            <groupId>io.quarkus.platform</groupId>
+            <artifactId>quarkus-bom</artifactId>
             <version>${quarkus.platform.version}</version>
             <type>pom</type>
             <scope>import</scope>
@@ -437,9 +437,9 @@ If you have not used <<project-creation,project scaffolding>>, add the following
 <build>
     <plugins>
         <plugin> <2>
-            <groupId>io.quarkus</groupId>
+            <groupId>io.quarkus.platform</groupId>
             <artifactId>quarkus-maven-plugin</artifactId>
-            <version>${quarkus-plugin.version}</version>
+            <version>${quarkus.platform.version}</version>
             <extensions>true</extensions> <3>
             <executions>
                 <execution>

docs/src/main/asciidoc/optaplanner.adoc

@@ -82,8 +82,15 @@ In Maven, your `pom.xml` file contains these dependencies:
   <dependencyManagement>
     <dependencies>
       <dependency>
-        <groupId>io.quarkus</groupId>
-        <artifactId>quarkus-universe-bom</artifactId>
+        <groupId>io.quarkus.platform</groupId>
+        <artifactId>quarkus-bom</artifactId>
+        <version>{quarkus-version}</version>
+        <type>pom</type>
+        <scope>import</scope>
+      </dependency>
+      <dependency>
+        <groupId>io.quarkus.platform</groupId>
+        <artifactId>quarkus-optaplanner-bom</artifactId>
         <version>{quarkus-version}</version>
         <type>pom</type>
         <scope>import</scope>
@@ -121,7 +128,8 @@ In Maven, your `pom.xml` file contains these dependencies:
 //[source,groovy,subs=attributes+]
 //----
 //dependencies {
-//    implementation enforcedPlatform("io.quarkus:quarkus-universe-bom:{quarkus-version}")
+//    implementation enforcedPlatform("io.quarkus.platform:quarkus-bom:{quarkus-version}")
+//    implementation enforcedPlatform("io.quarkus.platform:quarkus-optaplanner-bom:{quarkus-version}")
 //    implementation 'io.quarkus:quarkus-resteasy'
 //    implementation 'io.quarkus:quarkus-resteasy-jackson'
 //    implementation 'org.optaplanner:optaplanner-quarkus'

docs/src/main/asciidoc/platform.adoc

@@ -46,10 +46,10 @@ To be able to easily identify Quarkus platform descriptors among the project's d
 
 As a string it will look like `<platform-bom-groupId>:<platform-bom-artifactId>-quarkus-platform-descriptor:<platform-version>:json:<platform-version>`
 
-E.g. the coordinates of the descriptor for Quarkus BOM `io.quarkus:quarkus-bom::pom:1.2.3` will be `io.quarkus:quarkus-bom-quarkus-platform-descriptor:1.2.3:json:1.2.3`.
+E.g. the coordinates of the descriptor for the Quarkus BOM `io.quarkus.platform:quarkus-bom::pom:1.2.3` will be `io.quarkus.platform:quarkus-bom-quarkus-platform-descriptor:1.2.3:json:1.2.3`.
 And for a custom Quarkus platform defined with BOM `org.acme:acme-bom::pom:555` it will be `org.acme:acme-bom-quarkus-platform-descriptor:555:json:555`.
 
-The classifier matching the version of the platform may look confusing at first. But this is what turns the descriptor into a true "fingerprint" of the platform. In both Maven and Gradle, the effective set of the dependency version constraints (or the managed dependencies) is obtained by merging all the imported BOMs and version constraints specified individually in the current project and also its parent(s). The artifact `classifier` is a part of the dependency ID, which could be expressed as `groupId:artifactId:classifier:type`. Which means that if a project is based on a couple of Quarkus platforms (by importing their BOMs), e.g. `io.quarkus:quarkus-universe-bom::pom:1.2.3` and `org.acme:acme-bom::pom:555`, and these two platforms are based on different `io.quarkus:quarkus-bom::pom` versions (which is technically a Quarkus platform in its turn as well), the Quarkus tools will be able to detect this fact and make the user aware of it, since it *might* not be a safe combination. If the descriptor artifact didn't include the classifer containing the version of the platform then the tools wouldn't be able to detect a potentially incompatible mix of different versions of the same platform in the same project.
+The classifier matching the version of the platform may look confusing at first. But this is what turns the descriptor into a true "fingerprint" of the platform. In both Maven and Gradle, the effective set of the dependency version constraints (or the managed dependencies) is obtained by merging all the imported BOMs and version constraints specified individually in the current project and also its parent(s). The artifact `classifier` is a part of the dependency ID, which could be expressed as `groupId:artifactId:classifier:type`. Which means that if a project imports a couple of BOMs, e.g. `org.apple:apple-bom::pom:1.0` and `org.orange:orange-bom::pom:1.0`, and each of these two BOMs imports a different version `io.quarkus.platform:quarkus-bom::pom`, the Quarkus tools will be able to detect this fact and make the user aware of it, since it *might* not be a safe combination. If the descriptor artifact didn't include the classifer containing the version of the platform then the tools wouldn't be able to detect a potentially incompatible mix of different versions of the same platform in the same project.
 
 The platform descriptor will normally be generated using a Maven plugin, e.g.
 
@@ -157,26 +157,26 @@ IMPORTANT: The content of the properties artifacts found earlier will dominate o
 
 That means if a platform needs to override a certain property value defined in the platform it is based on, it will need to include its platform properties artifact into the `managedDependencies` section of its BOM before importing the base platform.
 
-For example, the `quarkus-universe-bom` platform is based on the `quarkus-bom` platform. In case, the `quarkus-universe-bom` platform were to override certain properties defined in `quarkus-bom-quarkus-platform-properties` included into the `quarkus-bom` platform, the `quarkus-universe-bom` would have to be composed as
+For example, let's assume `org.acme:acme-quarkus-bom` platform extends the `io.quarkus:quarkus-bom` platform by importing its BOM. In case, the `org.acme:acme-quarkus-bom` platform were to override certain properties defined in the `io.quarkus:quarkus-bom-quarkus-platform-properties` included in the `io.quarkus:quarkus-bom`, the `org.acme:acme-quarkus-bom` would have to be composed as
 [source,xml]
 ----
   <!-- skipped content -->
 
-  <artifactId>quarkus-universe-bom</artifactId>
-  <name>Quarkus universe - BOM</name>
+  <artifactId>acme-quarkus-bom</artifactId>
+  <name>Acme - Quarkus - BOM</name>
   <packaging>pom</packaging>
 
   <dependencyManagement>
     <dependencies>
-      <!-- universe platform properties -->
+      <!-- Acme Quarkus platform properties -->
       <dependency>
-        <groupId>io.quarkus</groupId>
-        <artifactId>quarkus-universe-bom-quarkus-platform-properties</artifactId>
+        <groupId>org.acme</groupId>
+        <artifactId>acme-quarkus-bom-quarkus-platform-properties</artifactId>
         <type>properties</type>
         <version>${project.version}</version>
       </dependency>
 
-      <!-- Quarkus Core BOM -->
+      <!-- The base Quarkus BOM -->
       <dependency>
         <groupId>io.quarkus</groupId>
         <artifactId>quarkus-bom</artifactId>
@@ -188,4 +188,4 @@ For example, the `quarkus-universe-bom` platform is based on the `quarkus-bom` p
   <!-- skipped content -->
 ----
 
-That way, the `quarkus-universe-bom` platform properties will appear before the `quarkus-bom` platform properties and so will be dominating during merging.
+That way, the `org.acme:acme-quarkus-bom` platform properties will appear before those provided by the `io.quarkus:quarkus-bom` properties and so will be dominating at build time.