Zowe lacks strategy on Downgrades and Upgrades

[1000TurquoisePogs]

Regarding Zowe upgrades and downgrades, especially of the servers, I do not see anything in the documentation that covers how to perform them, and I don't see any document covering how we as a project prevent unintended breaks and changes that would prevent such downgrades/upgrades.

Downgrade challenges

• If there's a new zowe YAML used on an old zowe, what happens?
• If there's a new workspace used on an old zowe, what happens?
• If you use an old launcher with new YAML, does it crash?
• If you use an old STC JCL, you'll have bugs we already fixed.

Upgrade challenges

• Usually, certificates and security items don't change version to version. So ideally we can tell users to skip redoing them. But if they do change, we have to notify about that exception!
• Usually, old YAML can work with new Zowe. But if that's not true, we need to notify!

To solve these challenges, we need process that we stick to so that we can guarantee some behaviors the users can follow.

I propose the following draft documentation on the subjects:

Upgrades

Upgrading Zowe server installs requires performing the SMPE installation (or running zwe install when using the PAX distribution of Zowe) and the following configuration tasks

Task	Description	Sample JCL	zwe command
Create Instance Datasets	Purpose: Create datasets for Zowe's PARMLIB content and non-ZFS extension content for a given Zowe Instance Action: 1) Allocate PDSE FB80 dataset with at least 15 tracks named from Zowe parameter zowe.setup.dataset.parmlib 2) Allocate PDSE FB80 dataset with at least 30 tracks named from Zowe parameter zowe.setup.dataset.authPluginLib 3) Copy ZWESIP00 member from zowe.setup.dataset.prefix.SZWESAMP into zowe.setup.dataset.parmlib	ZWEIMVS	zwe init mvs
APF Authorize privileged content	Purpose: Zowe contains one privileged component, ZIS, which enables the security model by which the majority of Zowe is unprivileged and in key 8. The load library for the ZIS component and its extension library must be set APF authorized and run in key 4 to use ZIS and components that depend upon it. Action: 1) APF authorize the datasets defined at zowe.setup.dataset.authLoadlib and zowe.setup.dataset.authPluginLib. 2) Define PPT entries for the members ZWESIS01 and ZWESAUX as Key 4, NOSWAP in the SCHEDxx member of the system PARMLIB.	ZWEIAPF	zwe init apfauth
Copy STC JCL to PROCLIB	Purpose: ZWESLSTC is the job for running Zowe's webservers, and ZWESISTC is for running the APF authorized cross-memory server. The ZWESASTC job is started by ZWESISTC on an as-needed basis. Action: Copy the members ZWESLSTC, ZWESISTC, and ZWESASTC into your desired PROCLIB. If the job names are customized, also modify the YAML values of them in zowe.setup.security.stcs	ZWEISTC	zwe init stc

Any other change required upon upgrade, such as security, networking, certificate, or configuration changes will be stated within SMPE HOLD statements and release notes.

The tasks can also be performed via z/OSMF workflow ZWECONF or via the Zowe Server Install Wizard, however, these also perform tasks such as security, networking, and certificate setup that are not needed with each upgrade.

Downgrades

Each version of Zowe is comprised of the following read-only, runtime content:

Item	Location	Description
LOADLIB	SMPE managed <zowe>.SZWELOAD	Contains libraries used for configuration management
APF LOADLIB	SMPE managed <zowe>.SZWEAUTH	Used for ZIS
SAMPLIB	SMPE managed <zowe>.SZWESAMP	Contains sample jobs for setup
EXECLIB	SMPE managed <zowe>.SZWEEXEC	Contains tools used by setup
Runtime	ZFS location found in YAML zowe.runtimeDirectory	Contains majority of zowe server code

Each instance of Zowe has the following configuration or setup related content:

Item	YAML value	Description
JCLLIB	zowe.setup.dataset.jcllib	Scratch area of jobs derived from SAMPLIB, used during setup
PARMLIB	zowe.setup.dataset.parmlib	Used for configuration of ZIS and its plugins
Auth Plugin LOADLIB	zowe.setup.dataset.authPluginLib	Stores ZIS plugins
Proclib ZIS job	zowe.setup.security.stcs.zis	Runs ZIS
Proclib Main job	zowe.setup.security.stcs.zowe	Runs Zowe unix content
Proclib Aux job	zowe.setup.security.stcs.aux	Used by ZIS on as-needed basis
Workspace directory	zowe.workspaceDirectory	Stores persistent configuration data
Extension directory	zowe.extensionDirectory	Stores or references Zowe extensions
Zowe YAML	N/A	References the above elements, and various other configuration values

To downgrade, you should first back up these assets.
Then, you can return to an earlier version upon restoring from such backups.