update proposal

Signed-off-by: Jeff Mesnil <[email protected]>

wf-galleon/wildfly_channel_in_zips.adoc

@@ -20,33 +20,76 @@ WildFly now publishes https://repo1.maven.org/maven2/org/wildfly/channels/[chann
 This works out of the box if users is provisioning WildFly (using the wildfly-maven-plugin or Prospero).
 However for users that are downloading WildFly from our traditional distributions (zip & tgz archives) they can not take advantage of this mechanism.
 
-If our archives would work out of the box with channels, it would significantely simplify updating an installation.
+If WildFly archives would work out of the box with channels, it would significantely simplify updating an installation.
 
 The workflow would be as simple as:
 
 1. Download WildFly version x.y.z from our download page
 2. Use it as normal
-3. A micro release of WildFly x.y.(z+ 1) is made available
-4. Run a script in the existing WildFly installation to update if from x.y.z to x.y.(z+1)
-5. Reload the server to run your applications on WildFly x.y.(z+ 1)
+3. A more recent version of WildFly x.y.(z+ 1) is made available
+4. Run a script in the existing WildFly installation to update it to this new version
+5. Restart the server to run your applications on this new version
 
 If there are multiple available updates for WildFly, the user must be able to decide which one they want to update to.
 This lets the user decide whether they want to update to the latest micro release or the next major release.
 
+=== WildFly Channels
+
+WildFly channels are published for each of its distributions since 32.0.0.Beta1:
+
+* https://repo1.maven.org/maven2/org/wildfly/channels/wildfly/[org.wildfly.channels:wildfly] 
+* https://repo1.maven.org/maven2/org/wildfly/channels/wildfly-ee/[org.wildfly.channels:wildfly-ee] 
+* https://repo1.maven.org/maven2/org/wildfly/channels/wildfly-preview/[org.wildfly.channels:wildfly-preview]
+
+These channels are versioned based on the WildFly versions (e.g. `org.wildfly.channels:wildfly:32.0.1.Final` contains all the dependencies to provision WildFly 32.0.1.Final's full installation)
+
+The http://docs.wildfly.org/wildfly-proposals/build/WFLY-19130_publish_Wildfly_channel_manifest.html[Analysis Document for WFLY-19130] states that the channels publish the latest manifest with no backwards compatibility guarantee, meaning each channel will always contain components of the latest released version of WildFly.
+
+There are no guarantee that the channel will not break between major releases of WildFly.
+We guarantee that minor and micro releases of WildFly do not contain breaking changes and this extends to their channels.
+
+=== Tooling Workflow
+
+With that in mind, we propose to incorporate the channel metadata in the WildFly distributions that describes the exact version of the channel used to provision the server.
+In practice, that means that the installation would be "stuck" to a versioned channel (eg `org.wildfly.channels:wildfly:33.0.0.Final`).
+
+Updating to a more recent version is a user decision and would require the user to give as input the version of the WildFly they want to _update to_ (e.g. `33.0.1.Final` or `34.0.0.Final`).
+After the update is successful, the channel metadata would be updated to point to the current version of the installation.
+
+WildFly must contain the tooling to let user update installations without having to download another piece of software.
+
+The tooling should be made available in the `bin` directory of this installation and affects only the parent directory (`JBOSS_HOME` would have no bearing for update).
+
+The tooling would need to provide the following operations:
+
+* List the actual provisioned version of the installation (the channel it was provisioned from, read from the metadata added by WFLY-19221)
+** Informational only - no changes to the installation state
+* List the available updates for the installations (can be obtained by querying Maven Central to get all the versions for the channel artifact based on the maven-metadata.xml)
+** Informational only - no changes to the installation state
+* Apply an update to a more recent version of WildFly (based on the list mentioned above)
+** Verify that the installation is not running.
+** The changes that would be applied to the installation are shown to the user
+** After their confirmation, the update is applied and the installation state changes
+** After the update, the provisioned version of the installation is the more recent version that was applied
+
+Since https://issues.redhat.com/browse/WFCORE-6206[WFCORE-6206], there is `installation-manager` script that is meant for internal usage. This script could be repurposed to provide these operations to the user.
+
 
 == Issue Metadata
 
 === Issue
 
-* https://issues.redhat.com/browse/WFLY-19221
+* https://issues.redhat.com/browse/WFLY-19221 - [Preview] Incorporate channel metadata in the download zips
 
 === Related Issues
 
-* https://issues.redhat.com/browse/WFLY-19130
+* https://issues.redhat.com/browse/WFLY-19130 - [Community] Publish Wildfly channel and manifest during project build
+** http://docs.wildfly.org/wildfly-proposals/build/WFLY-19130_publish_Wildfly_channel_manifest.html[Analysis Document]
+* https://issues.redhat.com/browse/WFCORE-6206 - Add new module to allow an integration of an Installation Manager
 
 === Stability Level
 
-* [X] Experimental
+* [x] Experimental
 
 === Dev Contacts
 
@@ -56,12 +99,14 @@ This lets the user decide whether they want to update to the latest micro releas
 
 === Testing By
 
-* [X] Engineering
+* [x] Engineering
 
 === Affected Projects or Components
 
-* WildFly
-* Prospero
+* https://github.com/wildfly/wildfly[WildFly]
+** WildFly distributions will incorporate channel metadata used to create the distributions and tooling to update the installation to a more recent version.
+* https://github.com/wildfly-extras/prospero[Prospero]
+** Prospero will be used as the library to update WildFly installations but will not surface to the user (the `installation-manager` script is the user entry point)
 
 === Other Interested Projects
 
@@ -72,14 +117,19 @@ This lets the user decide whether they want to update to the latest micro releas
 == Requirements
 
 * WildFly distributions archives (zip & tgz) must contain the channel metadata that describes their installation state.
+** tracked by https://issues.redhat.com/browse/WFLY-19221[WFLY-19221]
+** Provisioned feature packs are referenced by their Maven artifacts coordinates (e.g. `org.wildfly:wildfly-galleon-pack:33.0.0.Final`) and not by their Galleon feature-pack-locations (e.g. `wildfly@maven(org.jboss.universe:community-universe):current#33.0.0.Final`).
 * WildFly distributions archives (zip & tgz) must contain the tooling (as scripts) to let users update their installations
+** not tracked in JIRA
 ** Users must be able to list and select the updates to apply to their installations
 ** The user MUST specify the updates to apply.
-** As this feature is experimental, the tooling should warn the user that udpating their installation is an experimental mechanism
+** As this feature is experimental, the tooling should warn the user that updating their installation is an experimental mechanism
+** these operations will be using Prospero that needs to be integrated as a JBoss module in the WildFly distributions.
 * Updates must not discard any user changes to an installation (in their configuration files or JBoss modules directory)
 
 === Non-Requirements
 
+* Changing the type of distributions during an update is not supported (in other words, it is not possible to download the zip for WildFly 33.0.0.Final and update the installation to WildFly Preview)
 * Trimming an existing installation coming from WildFly distributions with Galleon layers is not supported.
 
 === Future Work
@@ -92,29 +142,36 @@ This enhancement does not affect previous versions of WildFly.
 
 === Default Configuration
 
-Updating an installation could update its default configuration (eg if the update is to a major version).
+Updating an installation could update its default configuration (e.g. if the update is to a major version).
+
+WildFly does not make guarantee that its default configuration will be compatible from one major version to another (even though in practice, that's often the case).
 
-WildFly does not make guarantee that its default configuration will be compatible from one major version to another (even though in practice, that's often the case)
 
 === Importing Existing Configuration
 
-[jmesnil] TBD - I'm not sure what section means in the context of this enhancement
+This section is not relevant in the context of this enhancement.
 
 === Deployments
 
 Deployments can be affected by this enhancement if there are incompatibilities between the existing WildFly installation and the update.
 
-Testing an installation is out of scope of this enhancement but should be incorporated in the user workflow (eg to test the update in a staging environment).
+Testing an installation is out of scope of this enhancement but should be incorporated in the user workflow (e.g. to test the update in a staging environment).
 
 === Interoperability
 
+This section is not relevant in the context of this enhancement.
+
 == Test Plan
 
-TBD
+=== Test Plan for WFLY-19221 - [Preview] Incorporate channel metadata in the download zips
+
+* Verify that WildFly generated distributions (from the `dist`, `ee-dist`, and `preview-dist` Maven Modules) contain the channel metadata files corresponding to their provisioning states.
 
 == Community Documentation
 
-The https://docs.wildfly.org/32/Installation_Guide.html[Installation Guide] needs to be updated.
+WFLY-19221 does not require community documentation as it only ensures that the distributions contain the channel metadata to be _eventually_ updated.
+
+Once the tooling is in place to actually perform the updates, the https://docs.wildfly.org/32/Installation_Guide.html[Installation Guide] will have to be updated.
 
 Its section `Installing WildFly from a zipped distribution` would be expanded to include information about updating the installation.
 
@@ -123,5 +180,6 @@ The guide would let the users download WildFly (eg 33.0.0.Final), check if there
 
 == Release Note Content
 
+* Related to  WFLY-19221 - [Preview] Incorporate channel metadata in the download zips
 
-WildFly downloads can now be updated to more recent releases out of the box.
+> [Preview] WildFly archives (zip & tgz distributions) contain channel metadata required for future updates