From 0aae9dc7370b7c0d65e3269f7ac9171aafe9eb6e Mon Sep 17 00:00:00 2001 From: Brian Stansberry Date: Mon, 22 Jan 2024 20:28:13 -0600 Subject: [PATCH] [WFLY-18856] Document stability levels --- .../Core_management_concepts.adoc | 2 + .../Feature_stability_levels.adoc | 49 +++++++++++++++++++ .../Command_line_parameters.adoc | 7 +++ .../_galleon/Galleon_provisioning.adoc | 43 +++++++++++++--- 4 files changed, 93 insertions(+), 8 deletions(-) create mode 100644 docs/src/main/asciidoc/_admin-guide/Feature_stability_levels.adoc diff --git a/docs/src/main/asciidoc/_admin-guide/Core_management_concepts.adoc b/docs/src/main/asciidoc/_admin-guide/Core_management_concepts.adoc index cd71bdb70e95..cb8e2693ecbd 100644 --- a/docs/src/main/asciidoc/_admin-guide/Core_management_concepts.adoc +++ b/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[] diff --git a/docs/src/main/asciidoc/_admin-guide/Feature_stability_levels.adoc b/docs/src/main/asciidoc/_admin-guide/Feature_stability_levels.adoc new file mode 100644 index 000000000000..4eaf714a7c8a --- /dev/null +++ b/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 <>. + +[[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’. \ No newline at end of file diff --git a/docs/src/main/asciidoc/_admin-guide/management-tasks/Command_line_parameters.adoc b/docs/src/main/asciidoc/_admin-guide/management-tasks/Command_line_parameters.adoc index 78424b69118d..302386aed01e 100644 --- a/docs/src/main/asciidoc/_admin-guide/management-tasks/Command_line_parameters.adoc +++ b/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 diff --git a/docs/src/main/asciidoc/_galleon/Galleon_provisioning.adoc b/docs/src/main/asciidoc/_galleon/Galleon_provisioning.adoc index d954a070175c..6acb22bb99b5 100644 --- a/docs/src/main/asciidoc/_galleon/Galleon_provisioning.adoc +++ b/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. ====