Merge pull request #345 from jfdenise/main

Document features and packages stability level

docs/guide/index.adoc

@@ -40,6 +40,8 @@ include::user-managed-content/index.adoc[]
 
 include::provisioning-options/index.adoc[]
 
+include::stability-handling/index.adoc[]
+
 include::maven-plugin/index.adoc[]
 
 include::tool/index.adoc[]

docs/guide/provisioning-options/index.adoc

@@ -42,11 +42,19 @@ Provisioning options can be provided by the core provisioning mechanism itself a
 .Built-in provisioning options
 |===
 |Name |Purpose |Value set
+|config-stability-level |<<_stability_level,Stability level for configs>>. 
+This stability level is used to enable the stability level of all features present in the generated configurations. 
+By default the configs stability level set in the feature-pack is used.| `default`, `community`, `preview`, `experimental`
+|export-system-paths |<<_protected_system_files,Store the system paths declared by Feature Packs in .galleon/systempaths.txt>> | `false` _(default)_, `true`
 |ignore-not-excluded-layers |<<_excluding_layers_from_configuration_models,Suppresses the error when layers configured to be excluded would not have otherwise been installed>> |`false` _(default)_, `true`
 |optional-packages |<<_feature_pack_original_effective_package_set,Optional package dependencies inclusion policy>> |`all` _(default)_, `none`, `passive`, `passive+`
+|package-stability-level |<<_stability_level,Stability level for packages>>. This stability level is used to set the stability level of all provisioned packages.
+By default the packages stability level set in the feature-pack is used.| `default`, `community`, `preview`, `experimental`
+|stability-level |<<_stability_level,Stability level for both configs and packages>>. This option is a convenience 
+allowing to set both the config and package stability level using a single option. It can't be set when `config-stability-level` or `package-stability-level` are set| `default`, `community`, `preview`, `experimental`
+
 |store-input-provisioning-config |<<_storing_input_provisioning_config,Store the provisioning config received as input in the generated .galleon/provisioning.xml file>> |`false` _(default)_, `true`
 |version-convergence |<<_dependency_version_convergence,Disables or enables the dependency version convergence>> | `first-processed` _(default)_, `fail`
-|export-system-paths |<<_protected_system_files,Store the system paths declared by Feature Packs in .galleon/systempaths.txt>> | `false` _(default)_, `true`
 |===
 
 #### Product provisioning options

docs/guide/stability-handling/index.adoc

@@ -0,0 +1,29 @@
+## Stability Level
+
+A level of stability can be associated to features and packages.
+
+Stability levels are ordered in the following way:
+
+`default` (the higher level of stability) > `community` > `preview` > `experimental` (the lower stability level)
+
+A feature-pack can contain features and packages at different level of stability, allowing to provision installations at different stability levels.
+
+### Default stability levels
+
+When building a feature-pack, the `<feature-pack>` XML element contained in the `feature-pack.xml` descriptor can include attributes to specify 
+the default stability levels that will be enabled when using the feature-pack during provisioning. 
+If no such stability levels exist, `default` level is assumed.
+
+The stability attributes are:
+
+* `config-stability-level="<default|community|preview|experimental>"` attribute is used to declare the default stability level of the features present in the provisioned configurations.
+* `package-stability-level="<default|community|preview|experimental>"` attribute is used to declare the default stability level of the provisioned packages.
+
+### Stability levels can be overridden at provisioning time
+
+It is possible to control the expected level of stability at provisioning time by means of the following Galleon options:
+
+* `config-stability-level=<default|community|preview|experimental>`: To enable a given stability level for the provisioned configurations.
+* `package-stability-level=<default|community|preview|experimental>`: To enable a given stability level for the provisioned packages.
+* `stability-level=<default|community|preview|experimental>`: An option to enable both configs and packages stability levels. It can't be set when `config-stability-level` or `package-stability-level` are set.
+