Proposal for WFLY-19021, Stability support in WildFly provisioning

wf-galleon/WFLY-19021-Stability_In_Provisioning.adoc

@@ -0,0 +1,165 @@
+= WildFly provisioning to support WildFly stability
+:author:            Jean-Francois Denise
+:email:             jdenise@redhat.com
+:toc:               left
+:icons:             font
+:idprefix:
+:idseparator:       -
+
+== Overview
+
+WildFly 31 introduced the notion of stability level. Galleon, WildFly Galleon plugins and provisioning tooling must be evolved to support this notion.
+This proposal describes how stability is handled by the WildFly provisioning. 
+
+== Issue Metadata
+
+=== Issue
+
+* https://issues.redhat.com/browse/WFLY-19021[WFLY-19021] - WildFly provisioning to support WildFly stability
+
+=== Related Issues
+
+* https://issues.redhat.com/browse/WFCORE-6668[WFCORE-6668] - Ensure read-feature-description results contain stability as reported by associated description for use by WildFly Glow
+* https://issues.redhat.com/browse/WFGP-265[WFGP-265] - Support setting a minimum stability level when provisioning
+* https://issues.redhat.com/browse/WFGP-264[WFGP-264] - Support setting a minimum stability level when building a feature pack
+* https://issues.redhat.com/browse/GAL-357[GAL-357] - Support for feature/package stability
+
+
+=== Dev Contacts
+
+* mailto:{email}[{author}]
+
+=== QE Contacts
+
+* XXX
+
+=== Testing By
+// Put an x in the relevant field to indicate if testing will be done by Engineering or QE. 
+// Discuss with QE during the Kickoff state to decide this
+* [x] Engineering
+
+* [ ] QE
+
+=== Affected Projects or Components
+
+* https://github.com/wildfly/wildfly[WildFly]
+* https://github.com/wildfly/galleon-plugins[WildFly Galleon plugins]
+* https://github.com/wildfly/galleon[Galleon]
+* https://github.com/wildfly/wildfly-glow[WildFly Glow]
+
+=== Relevant Installation Types
+// Remove the x next to the relevant field if the feature in question is not relevant
+// to that kind of WildFly installation
+* [x] Traditional standalone server (unzipped or provisioned by Galleon)
+
+* [x] Managed domain
+
+* [x] OpenShift s2i
+
+* [x] Bootable jar
+
+== Requirements
+
+Stability becomes a Galleon notion that applies to feature-pack, feature/feature_param and package.
+There is a 1 to 1 mapping with WildFly stability.
+The stability levels are: `default` < `community` < `preview` < `experimental`
+
+=== Requirements at feature-pack build time
+
+==== feature-pack minimum stability level
+
+A minimum stability level can be set at feature-pack build time. If no stability level is specified, the `default` level is used.
+
+Stability level is set thanks to a new option of the WildFly Galleon Plugins Maven plugin: 
+`<minimum-stability>default|community|preview|experimental</minimum-stability>`
+
+==== JBoss Modules modules stability level
+
+A stability level can be set in `module.xml` thanks to the property `org.jboss.stability`. 
+Possible value being `default|community|preview|experimental`. If no stability is specified, `default` is assumed.
+
+==== Implementation notes
+
+At build time, this minimum stability level is used in 2 cases:
+
+* To start the embedded server that generates the Galleon features at the correct stability level (allowing the features to be discovered in the server).
+* To filter-out packages at a stability level lower than the minimum-stability level. Such packages are not packaged inside the feature-pack.
+
+==== Stability for WildFly feature-packs
+
+Expected minimum stability levels for WildFly feature-packs:
+
+* wildfly-ee-galleon-pack: `experimental`
+* wildfly-galleon-pack: `experimental`
+* wildfly-preview-feature-pack: `experimental`
+
+=== Requirements at provisioning time
+
+Provisioning time follows some rules to properly handle stability and avoid features/packages of wrong stability to be provisioned.
+
+* The feature-pack contained minimum stability level is used to constrain the set of provisioned features. Any features/packages at a lower stability level contained in the 
+feature-pack (if any), are not provisioned.
+* By default, the minimum stability level of each feature-pack is used when provisioning its own content. 
+* Each feature-pack present in the provisioning configuration can have a different minimum stability level. 
+The minimum stability of each feature-pack applies to its own content and doesn't leak into other feature-packs.
+* A user can specify a stability-level, by the mean of the `stability-level` Galleon option. 
+This stability level is used to constrain the stability level of all provisioned features/packages. If the specified level is lower than a feature-pack minimum stability, 
+the feature-pack minimum stability is used.
+
+For example, a provisioning configuration containing 3 feature-packs:
+
+* A, minimum stability default
+* B, minimum stability community
+* C, minimum stability experimental
+
+If no stability level is specified:
+
+* `default` features/packages of A are provisioned
+* `community` and `default` features/packages of B are provisioned
+* `experimental`, `preview`, `community` and `default` features/packages of C are provisioned
+
+If the stability level `default` is specified:
+
+* `default` features/packages of A are provisioned
+* `default` features/packages of B are provisioned
+* `default` features/packages of C are provisioned
+
+If the stability level `experimental` is specified:
+
+* `default` features/packages of A are provisioned
+* `community` and `default` features/packages of B are provisioned
+* `experimental`, `preview`, `community` and `default` features/packages of C are provisioned
+
+==== Lowest stability level needed by WildFly Galleon Plugins
+
+At provisioning time, when WildFly Galleon plugin generates the server configurations, 
+a WildFly embedded server is started. This server is started with a stability level computed in the following way:
+
+* If a stability level has been specified by the user, this level is used.
+* If no stability level has been specified, the lowest minimum stability level of all feature-packs present in the provisioning is used.
+
+=== Provisioning tooling requirement
+
+* All Galleon based tooling should let users specify the `stability-level` option.
+* In addition, for WildFly Glow, information about the features/packages that would be not provisioned for a given stability level 
+is displayed to the user.
+
+=== Nice-to-Have Requirements
+
+* NONE
+
+=== Non-Requirements
+
+* NONE
+
+== Backwards Compatibility
+
+* Galleon must be backward compatible with older WildFly releases not supporting stability.
+
+== Test Plan
+
+* Add new tests to Galleon project.
+
+== Community Documentation
+
+* Add documentation to Galleon and WildFly Glow.