Merge pull request wildfly#17547 from bstansberry/WFLY-18856

[WFLY-18856] Document stability levels

docs/src/main/asciidoc/_admin-guide/Core_management_concepts.adoc

@@ -19,6 +19,8 @@ ifdef::basebackend-html[toc::[]]
 
 include::Operating_modes.adoc[]
 
+include::Feature_stability_levels.adoc[]
+
 include::General_configuration_concepts.adoc[]
 
 include::Management_resources.adoc[]

docs/src/main/asciidoc/_admin-guide/Feature_stability_levels.adoc

@@ -0,0 +1,49 @@
+[[Feature_stability_levels]]
+= Feature stability levels
+ifdef::env-github[]
+:tip-caption: :bulb:
+:note-caption: :information_source:
+:important-caption: :heavy_exclamation_mark:
+:caution-caption: :fire:
+:warning-caption: :warning:
+endif::[]
+
+The WildFly project has high standards related to quality, stability and backwards compatibility. A key way an open source project like WildFly can ensure high standards are met is by "community bake" -- allowing interested users to have access to features that are still undergoing a hardening process, while not forcing users who are not interested in such things to consume them.
+
+To better facilitate this, WildFly 31 introduced the notion of formal "stability levels" that can be associated with functionality. When starting a WildFly process, users can use the `--stability` command line parameter to control the minimum stability level of available features, with a value of `experimental`, `preview`, `community` or `default`.
+
+[source,options="nowrap"]
+----
+bin/standalone.sh --stability=preview
+----
+
+Features at a lower stability level will not be available for use.
+
+A WildFly installation will have a standard stability level, determined by the xref:Galleon_Guide.adoc#WildFly_Galleon_feature-packs[Galleon feature-pack] used to provision the installation. This level is used if the `--stability` param is not set. For a standard WildFly installation, this level is `community`. For WildFly Preview it is `preview`.
+
+Some details on the stability levels:
+
+* *experimental* -- This level is for true bleeding edge functionality that may never advance to a higher stability level. No WildFly feature-pack or distribution zip/tar would enable this level by default.
+* *preview* -- This is the level for features that are of a sufficient stability to be available by default in WildFly Preview, but not in standard WildFly. The general expectation for features at this level is that they will eventually move to `community` level in substantially similar form (although this is not guaranteed).
+* *community*-- This is the level for features that are of a sufficient stability to be available by default in standard WildFly. Features at this level are not expected to change incompatibly over time in a manner inconsistent with the expectations of the xref:Galleon_Guide.adoc#WildFly_Galleon_feature-packs[Galleon feature-pack] that provides them.
+* *default* -- Features at this level have gone through additional vetting to ensure they are suitable for the long-term compatibility expectations of the xref:Galleon_Guide.adoc#WildFly_Galleon_feature-packs[Galleon feature-pack] that provides them.
+
+[NOTE]
+The vast majority of functionality provided in both xref:WildFly_and_WildFly_Preview.adoc[standard WildFly and WildFly Preview] is at the `default` stability level. Over time the amount of functionality at other levels, particularly `community`, is expected to increase.
+
+[NOTE]
+A feature being ‘available by default’ in a WildFly installation might not mean ‘enabled by default’, i.e. turned on in a standard out-of-the-box configuration. It could just mean a user could turn it on if they so choose using normal configuration tools like the <<Command_Line_Interface,CLI>>.
+
+[[Relationship_to_Feature_Packs]]
+== Relationship to feature-packs
+
+The xref:Galleon_Guide.adoc#WildFly_Galleon_feature-packs[Galleon feature-packs] that WildFly produces themselves incorporate expectations for long-term feature stability and compatibility. The `--stability` startup setting discussed above just allows users to use a different setting than the standard one for the feature-pack.
+
+* *wildfly-ee* -- This feature-pack is not widely used directly and WildFly does not produce any downloadable zip/tar built solely using it. However, it is transparently used internally in provisioning any standard WildFly installation, and most standard WildFly functionality is provisioned from this feature-pack. It can be used directly by users who wish to limit their installation to what it provides. The defining characteristic of this feature-pack is that it integrates technologies where we have the highest confidence in our ability to provide them in a largely compatible way for many years.
+* *wildfly* -- This is the feature-pack most people use. It depends upon `wildfly-ee` and adds functionality in addition to what is provisioned by `wildfly-ee`. The traditional standard WildFly server zip is built using this feature-pack. The primary reason things are provided in this feature-pack instead of `wildfly-ee` is because the technology that is integrated is more likely to change in incompatible ways over a relatively short time period. For example, MicroProfile specifications are comfortable introducing breaking changes on an annual basis, making them a poor fit for `wildfly-ee`. The observability space, particularly metrics and tracing, is evolving rapidly, so our Micrometer and OpenTelemetry extensions are not in `wildfly-ee`.
+* *wildfly-preview* -- This feature-pack provisions WildFly Preview and is all about the fact that it provides no long term guarantees and can change significantly from release to release.
+
+What we mean by the `community` and `default` levels is relative to the generally expected long-term maintainability and compatibility level of the feature-pack that provides it. In other words, just because a feature provided by the `wildfly` feature-pack has been vetted as suitable for the `default` level does not mean it comes with higher expectations than the feature-pack as a whole.
+
+[NOTE]
+WildFly Preview is also used to showcase functionality whose scope is not tied to a particular reasonably scoped ‘feature’. Using it in the past for Jakarta EE 9 was an example. Not having an embedded messaging broker in the standard configs is not a ‘feature’.

docs/src/main/asciidoc/_admin-guide/management-tasks/Command_line_parameters.adoc

@@ -212,6 +212,9 @@ versioned history is maintained of the file.
 |--git-branch |master |The Git branch or tag to be used. If a `tag` name is used then the future commits will go into the detached state.
 
 |--git-auth |- |A URL to an Elytron configuration file containing the credentials to be used for connecting to the Git repository.
+
+|--stability |community (__standard__ WildFly)
+preview (WildFly _Preview_)|Minimum xref:Feature_stability_levels.adoc#Feature_stability_levels[feature stability level] that the server should support. Features with a lower stability level will not be exposed by the management API.
 |=======================================================================
 
 [[managed-domain-1]]
@@ -245,6 +248,10 @@ relative to jboss.domain.config.dir. This is similar to --host-config
 but if this alternative is specified the host controller will not
 overwrite the file when the management model is changed. However, a full
 versioned history is maintained of the file.
+
+|--stability |community (__standard__ WildFly)
+preview (WildFly _Preview_)|Minimum xref:Feature_stability_levels.adoc#Feature_stability_levels[feature stability level] that the server should support. Features with a lower stability level will not be exposed by the management API. All
+Host Controllers in the domain must have the same `stability` setting.
 |=======================================================================
 
 The following parameters take no value and are only usable on secondary host

docs/src/main/asciidoc/_galleon/Galleon_provisioning.adoc

@@ -21,22 +21,49 @@ Releases of the Galleon command line tool are available on the Galleon link:http
 
 Download and unzip the release zip and add the `bin` dir to your system path. Use `galleon.sh` or `galleon.bat` to launch the tool.
 
+[[WildFly_Galleon_feature-packs]]
 == WildFly Galleon feature-packs
 
-WildFly provides a Galleon feature-pack maven artifact (a zipped file that contains 
-everything needed to dynamically provision a server). 
-This feature-pack, as well as the feature-packs on which its depends,
-are deployed in public maven repositories. 
+The WildFly project provides a number of Galleon https://docs.wildfly.org/galleon/#_feature_packs[feature-pack] maven artifacts. A feature-pack is a zipped file that contains everything needed to dynamically provision a server.
+These feature-packs are deployed in public maven repositories.
 
-When Galleon is used to install WildFly, WildFly feature-packs are retrieved and 
+When Galleon is used to install WildFly, the desired WildFly feature-packs are retrieved and
 their content is assembled to create an installation.
 
+The main WildFly project provides the following feature-packs for use with xref:WildFly_and_WildFly_Preview.adoc[standard WildFly]:
+
+[cols="~,~,~",options="header"]
+|=======================================================================
+|Maven GroupId:ArifactId |Short name|Use
+
+|*org.wildfly:wildfly-galleon-pack*|*wildfly*|The feature-pack most WildFly users use. Provisions a standard WildFly installation. Internally depends on the `wildfly-ee` feature-pack, but also provides integration of technologies like MicroProfile, Micrometer and Open Telemetry that are evolving rapidly, possibly in incompatible ways.
+|*org.wildfly:wildfly-ee-galleon-pack*|*wildfly-ee*|Provisions the most long-term stable functionality of standard WildFly. Does not include MicroProfile or other rapidly evolving technologies that may frequently introduce incompatible changes.
+|*org.wildfly.cloud:wildfly-cloud-galleon-pack*|-|Provisions a set of additional features allowing you to better configure a standard WildFly server to work on the cloud. It brings to the server some configuration aspects that are generally expected in a cloud context. See the feature-pack https://github.com/wildfly-extras/wildfly-cloud-galleon-pack/blob/main/doc/index.md[documentation] for more details.
+|*org.wildfly:wildfly-datasources-galleon-pack*|-|Easy integration of popular JDBC drivers and associated datasources into a standard WildFly installation. See the feature-pack project https://github.com/wildfly-extras/wildfly-datasources-galleon-pack/blob/main/README.md[README] for more details.
+|*org.wildfly:wildfly-myfaces-feature-pack*|-|Provides MyFaces 4.x support for standard WildFly. See the feature-pack project https://github.com/wildfly-extras/wildfly-myfaces-feature-pack/blob/master/README.md[README] for more details.
+|=======================================================================
+
+The main WildFly project also provides feature-packs for use with xref:WildFly_and_WildFly_Preview.adoc[WildFly Preview]:
+
+[cols="~,~,~",options="header"]
+|=======================================================================
+|Maven GroupId:ArifactId |Short name|Use
+
+|*org.wildfly:wildfly-preview-feature-pack*|*wildfly-preview*|Provides a technology preview of things that may be coming in standard WildFly. Likely to have significant incompatible changes with every release.
+|*org.wildfly.cloud:wildfly-preview-cloud-galleon-pack*|-|WildFly Preview analogue to *wildfly-cloud-galleon-pack*.
+|*org.wildfly:wildfly-datasources-preview-galleon-pack*|-|WildFly Preview analogue to *wildfly-datasources-galleon-pack*.
+|=======================================================================
+
+There are also a number of feature-packs of varying levels of stability available from the https://github.com/orgs/wildfly-extras/repositories[*wildfly-extras* GitHub organization].
+
+In most cases, people working with WildFly are using the `wildfly` feature-pack, so that is the one used in most of the examples in this document.
+
 == Installing WildFly using Galleon
 
 The Galleon maven plugin or Galleon CLI are used to install WildFly. The latest CLI and documentation can be downloaded 
 from the Galleon releases https://github.com/wildfly/galleon/releases[page].
 
-To install the latest final version of WildFly into the directory _my-wildfly-server_ call:
+To install the latest final version of standard WildFly into the directory _my-wildfly-server_ call:
 
 [source,options="nowrap"]
 ----
@@ -90,7 +117,7 @@ The _configuration name_ is the XML configuration file name (e.g.: _standalone.x
 [[wildfly_galleon_layers]]
 == WildFly Galleon layers
 
-WildFly Galleon feature-packs expose some link:++https://docs.wildfly.org/galleon/#_layers++[Galleon layers]. 
+WildFly Galleon feature-packs expose link:++https://docs.wildfly.org/galleon/#_layers++[Galleon layers].
 A layer identifies one or more server capabilities that can be installed on its own or
 in combination with other layers. For example, if your application (e.g. a microservice)
 is only making use of _Jakarta-RESTful-Web-Services_, MicroProfile Config and _CDI_ server capabilities, you can choose to only install
@@ -123,7 +150,7 @@ galleon.sh install wildfly:current --dir=my-wildfly-server --layers=cdi,jaxrs,-b
 [NOTE]
 ====
 
-* Tools (jboss-cli, add-user, ...) are not always installed when installing WildFly using layers.
+Tools (jboss-cli, add-user, ...) are not always installed when installing WildFly using layers.
 In some cases, depending on what layers you use, only server launcher scripts are installed into the _bin_ directory.
 To include these tools include the _core-tools_ layer.
 ====