From 5e5037ec5ee2ce675a5a1a40512901ceb5943ac0 Mon Sep 17 00:00:00 2001 From: anaxceron Date: Thu, 14 Nov 2024 15:28:28 -0500 Subject: [PATCH 01/14] adding workflow for major release doc updates Signed-off-by: anaxceron --- release-handbook/major_release_workflow.md | 184 +++++++++++++++++++++ release-handbook/release_handbook.md | 7 +- 2 files changed, 189 insertions(+), 2 deletions(-) create mode 100644 release-handbook/major_release_workflow.md diff --git a/release-handbook/major_release_workflow.md b/release-handbook/major_release_workflow.md new file mode 100644 index 0000000000..802a58680b --- /dev/null +++ b/release-handbook/major_release_workflow.md @@ -0,0 +1,184 @@ +# How to manage doc for a major Zowe release + +Major Zowe releases follow a similar publication process to that of minor releases: content is staged, and then that content is published to the live Zowe Docs site. + +What is quite different about updating documentation for a major release is the amount and type of prep work required. To improve the chances of a smoother publication process, you will want to start preparing the doc work for a major release at least a year ahead of the major release GA date. + +Zowe major releases are typically done about every two years or so. Minor releases take place about once a calendar quarter. + +The publication process for minor releases is documented in the [Release handbook](release_handbook.md). + +For major Zowe releases, follow the process outlined here. + +## Major release publication process + +1. At least a year before the major release GA, Doc Squad works together to create a release strategy. + - Strategy to include: + - Schedule for reviewing existing content for any needed modifications + - Schedule for when modifications should be drafted, reviewed, and completed + - Complete inventory of Zowe Docs content and the people who are responsible for ensuring that content is ready for the major release. + - Assignment of responsibilities. +2. Create a new branch based off the `master` branch to be dedicated to the major release documentation. Open the new branch in Visual Studio Code. + - For example, `v3-doc-branch` was used for the Zowe V3 release. +3. Archive the documentation for the most recent (minor) release by taking the following steps in this order: + - In the Terminal, run `npm run docusaurus docs:version `. + + - *\* is the version number of the previous release. + + Example: At the time you create the new branch, Zowe 3.5 is the latest version for the current major release. That means the command must be issued as `npm run docusaurus docs:version v3.5.x` + + - When the command completes, it returns the message `[docs]: version v3.5.x created!` + + - The document versioning mechanism has: + * Copied the full `docs/` folder contents into a new `versioned_docs/version-v3.5.x/` folder. + * Created a versioned `sidebars` file based from your current sidebar configuration. The file is saved as `versioned_sidebars/version-v3.5.x-sidebars.json`. + * Appended the new version number to the `versions.json` file. + + - Archive the `/static` files: + 1. Go to the `/static` folder. + 2. Create an empty directory with the name of the previous version in `/static`. For example: `static/v3.5.x`. + 3. Copy all contents of the `/static/stable` directory and paste them in the previous version's empty directory in the previous step. For example: `/static/v3.5.x`. + + - Update a set of links in the archived documentation to ensure that they refer to the correct location: + + 1. To do this, switch to the archived directory. In our example, that's `versioned_docs/version-v3.5.x`. + + 2. Update several locations in the archived docs to refer to the correct release, the 3.5 release (in our example case). + + **Tip**: Use the **Find** function of Visual Studio Code editor to make the updates. In our example, you can right-click the `versioned_docs/version-v3.5.x` folder and then select **Find in Folder...**. + + ![Find in files in VSCode](images/vscode-find.png) + + - Search all instances of `` and replace `stable` in the link with the previous version before adding the new version. Example: ``. + + ![Update CLI web help](images/update-cli-web-help.png) + + - Search all instances of `` and replace `stable` with the previous version before adding the new version. Example: ``. + + ![Update CLI reference PDF](images/update-cli-reference.png) + + - Search all instances of `` and replace `stable` with the previous version before adding the new version. Example: ``. + + ![Update CLI web help ZIP](images/update-cli-help-zip.png) + + 3. Verify that the archived version works: + 1. Run `npm install`. + 2. Run `npm start` to build the site locally and clear any errors. + + ![Verify the archived doc](images/verify-archive.png) + + **NOTE:** When the local build displays in your web browser, expect to see the previous minor release version listed twice in the Zowe Docs version drop-down menu. You will fix this in Step 4. + +4. Bump the version of docs to the new major version (example: v4.0) by taking the following steps in this order: + - Navigate to the `/docusaurus.config.js` file. + - Change the `LATEST_VERSION` variable present in Line 1 of the `/docusaurus.config.js` file to the new major version. + - Locate the presets: `> @docusaurus/preset-classic" > docs > versions` in the `/docusaurus.config.js` file to include the previous version in the list. + - Create an entry label for the previous version. + Example: If version v3.5.x docs is getting updated to v4.0.x, then v3.5.x will be appended between `current` and `v3.4.x` in the following format: + + ``` + presets: [ + [ + "@docusaurus/preset-classic", + { + docs: { + path: "docs", + sidebarPath: require.resolve("./sidebars.js"), + editUrl: "https://github.com/zowe/docs-site/edit/master/", + showLastUpdateAuthor: false, + showLastUpdateTime: true, + routeBasePath: "/", + lastVersion: "current", + versions: { + current: { + path: "stable", + label: `${LATEST_VERSION}` + " LTS", + }, + "v3.5.x": { + label: "v3.5.x LTS", + }, + "v3.4.x": { + label: "v3.4.x LTS", + }, + ``` + + - Open the `versions.json` file. Confirm that the previous release version number was added to the top of the list. (This is typically done automatically by the command issued in Step 3.) If not, manually add the version number. For example: + + ``` + [ + "v3.5.x", + "v3.4.x", + "v3.3.x", + "v3.2.x", + "v3.1.x", + "v3.0.x" + ] + ``` + +5. Create placeholder files to prep for the release notes and TPSRs: + - In Visual Studio Code, add the release notes placeholder file for the new major release: + 1. Go to `/docs/whats-new/release-notes`. + 2. Create a file for the new version and add the outline to the document. For example: `/docs/whats-new/release-notes/v4_0_0.md` + + To insert the outline, copy and paste the template from the [Release Notes guide](release_notes_guide.md). Ensure that you update the date and release version numbers included in the template. + + 3. Open the `sidebars.js` file and add the new page to the release notes section. + ``` + { + type: "category", + label: "Release notes", + items: [ + "whats-new/release-notes/v4_0_0", + "whats-new/release-notes/v3_5_0", + "whats-new/release-notes/v3_4_0", + ], + }, + ``` + + - Add the TPSR placeholder file. + 1. Go to the `/tpsr` directory. + 2. Add a new file for the new version. For example: `/tpsr/tpsr-v4.0.x.md`. + 3. Update the TPSR file URL the `sidebar.js` file: + + ``` + { + type: "link", + label: "Third Party Software Requirements", + href: "https://github.com/zowe/docs-site/tree/master/tpsr/tpsr-v4.0.x.md", + }, + ``` + + **Note:** This is just a placeholder file. The day before GA, this file should be updated to include the information for the new release. Contact the Zowe release engineer to get the most up-to-date file. + + - Create a local build to confirm everything works in your temporary branch. + + 1. Run `npm install`. + 2. Run `npm start` to build the site locally and clear any errors. +6. Create a PR in the `docs-site` repo to merge the new branch to the `docs-staging` branch. Set the PR to draft mode. + - At this point, the branch becomes available to Zowe community members for them to make any needed doc updates. You should now decide what restrictions (if any) to put in place to protect the branch. +7. As the GA date for the major release approaches, continue to sync the new branch with `docs-staging`. Resolve any merge conflicts that show up. This might mean checking in with the Doc Squad to confirm which content is the correct content to merge. +8. The day or two before the GA date, perform Step 3 to include the last minor release of the previous major version. +9. The day or two before the GA date, contact the release engineer to get the TPSR file. Add the TPSR file contents to the TPSR placeholder file in the repo. +10. Publish the staged doc to the live site: + - Change the PR you opened in Step 6 to **Ready for review** mode to merge the new branch into the `docs-staging` branch. + - All checks **must** pass before merging. If any checks fail, troubleshoot with Doc Squad members or developers well familiar with the `docs-site` repo to resolve. + - After the new branch is merged to `docs-staging`, create a PR to merge `docs-staging` into the `master` branch. + - In your PR, do the following: + - Add the Zowe release engineer to the reviewer list. + - Add Zowe Doc Squad maintainers to the reviewer list. + - Check the build status and notify the Doc Squad of any build problems or errors. + - Once the PR checks all pass, notify the release engineer that the PR has been created and needs review. It is the engineer who will merge the PR once the new release is published. + + **Important**: Remind the engineer to merge the PR by selecting the **Create a merge commit** option. + The engineer should **NOT** commit with a **Squash and merge**, which can lead to merge conflicts for later releases. + +11. Perform post-publication tasks: + - After the vNext content is live, create and publish a PDF of the content for new major release (v4.0, in our example): + 1. Follow the instructions in [Steps to manually generate PDF](pdf_generation_guide.md#steps-to-manually-generate-pdf-recommended). + 2. Create a new temporary branch to add the PDF to the `master` branch. Create and merge a PR in GitHub. + - Check Zowe Docs to confirm the site works as expected. Confirm the following items: + - The version dropdown menu includes all available versions + - Release notes are current + - The correct TPSRs are linked + - The PDF for the current release can be downloaded and viewed + - The Search functionality returns correct results diff --git a/release-handbook/release_handbook.md b/release-handbook/release_handbook.md index c4e0aac0e9..321f69dfcf 100644 --- a/release-handbook/release_handbook.md +++ b/release-handbook/release_handbook.md @@ -67,11 +67,13 @@ Once the Code Freeze for a new release takes place, the `docs-staging` branch mu - Creating placeholder files and folders for the vNext release The following steps takes v1.25 release preparation as an example. Preparation should start the day Code Freeze takes place. + ### **Part 1: Sync the doc branches** Summary: Update the `docs-staging` branch so it includes all updates made to the `master` branch. **Procedure** + 1. Create and publish a new (temporary) branch based off the `master` branch. 2. Create a PR to merge the temporary branch into the `docs-staging` branch. @@ -137,11 +139,11 @@ Summary: Create new directories to archive content. Relocate content files for t ![Update CLI web help](images/update-cli-web-help.png) - * Search all instaces of `` and replace `stable` with the previous version before adding the new version. Example: ``. + * Search all instances of `` and replace `stable` with the previous version before adding the new version. Example: ``. ![Update CLI reference PDF](images/update-cli-reference.png) - * Search all instaces of `` and replace `stable` with the previous version before adding the new version. Example: ``. + * Search all instances of `` and replace `stable` with the previous version before adding the new version. Example: ``. ![Update CLI web help ZIP](images/update-cli-help-zip.png) @@ -219,6 +221,7 @@ Summary: Using Visual Studio Code, update the necessary files to add the next re ``` Next: Create placeholder files to prep for vNext release notes and TPSRs. + ### **Part 4: Prepare new release files** Summary: Using Visual Studio Code, create placeholder files for the next release's release notes and TPSRs. Finish the staging process by merging your PR in GitHub. From 388f7d2688324ec3c763814aad8e324839111c92 Mon Sep 17 00:00:00 2001 From: Martin Zeithaml <66114686+Martin-Zeithaml@users.noreply.github.com> Date: Fri, 15 Nov 2024 15:27:11 +0100 Subject: [PATCH 02/14] Update install-zowe-zos-convenience-build.md Signed-off-by: Martin Zeithaml <66114686+Martin-Zeithaml@users.noreply.github.com> --- docs/user-guide/install-zowe-zos-convenience-build.md | 3 +++ 1 file changed, 3 insertions(+) diff --git a/docs/user-guide/install-zowe-zos-convenience-build.md b/docs/user-guide/install-zowe-zos-convenience-build.md index 39bff3240d..6479e4a4ca 100644 --- a/docs/user-guide/install-zowe-zos-convenience-build.md +++ b/docs/user-guide/install-zowe-zos-convenience-build.md @@ -140,6 +140,7 @@ Library DDNAME | Member Type | Target Volume | Type | Org | RECFM | LRECL | No. SZWESAMP | Samples | ANY | U | PDSE | FB | 80 | 15 | 5 SZWEAUTH | Zowe APF Load Modules | ANY | U | PDSE | U | 0 | 15 | N/A SZWEEXEC | CLIST copy utilities | ANY | U | PDSE | FB | 80 | 15 | 5 +SZWELOAD | Executable utilities library | ANY | U | PDSE | U | 0 | 15 | N/A The `SZWESAMP` data set contains the following members. @@ -167,6 +168,8 @@ ZWESAUX | Load module for the cross memory server's auxiliary address space The `SZWEEXEC` data set contains few utilities used by Zowe. +The `SZWELOAD` data set contains config manager for REXX. + ### Procedure The high level qualifer (or HLQ) for these data sets is specified in the `zowe.yaml` section below. Ensure that you update the `zowe.setup.dataset.prefix` value to match your system. From 090a4455c4964beaa33bfb18375cc5263bec0f7d Mon Sep 17 00:00:00 2001 From: Martin Zeithaml <66114686+Martin-Zeithaml@users.noreply.github.com> Date: Fri, 15 Nov 2024 16:48:31 +0100 Subject: [PATCH 03/14] Update install-zowe-zos-convenience-build.md Signed-off-by: Martin Zeithaml <66114686+Martin-Zeithaml@users.noreply.github.com> --- docs/user-guide/install-zowe-zos-convenience-build.md | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/user-guide/install-zowe-zos-convenience-build.md b/docs/user-guide/install-zowe-zos-convenience-build.md index 6479e4a4ca..eb8ada603d 100644 --- a/docs/user-guide/install-zowe-zos-convenience-build.md +++ b/docs/user-guide/install-zowe-zos-convenience-build.md @@ -197,6 +197,7 @@ A sample run of the command is shown below using default values. Create MVS data sets if they are not exist Creating Zowe sample library - IBMUSER.ZWEV2.SZWESAMP Creating Zowe authorized load library - IBMUSER.ZWEV2.SZWEAUTH +Creating Zowe load library - IBMUSER.ZWEV2.SZWELOAD Creating Zowe executable utilities library - IBMUSER.ZWEV2.SZWEEXEC Copy files/SZWESAMP/ZWESIPRG to IBMUSER.ZWEV2.SZWESAMP From 238ecc98f08eb8e956a61fb73abc11000f5c304a Mon Sep 17 00:00:00 2001 From: Andrew Jandacek Date: Mon, 18 Nov 2024 10:17:00 +0100 Subject: [PATCH 04/14] minor language and formatting refactor Signed-off-by: Andrew Jandacek --- .../install-zowe-zos-convenience-build.md | 16 ++++++++++------ 1 file changed, 10 insertions(+), 6 deletions(-) diff --git a/docs/user-guide/install-zowe-zos-convenience-build.md b/docs/user-guide/install-zowe-zos-convenience-build.md index eb8ada603d..d3f87d0074 100644 --- a/docs/user-guide/install-zowe-zos-convenience-build.md +++ b/docs/user-guide/install-zowe-zos-convenience-build.md @@ -52,8 +52,10 @@ After you download the PAX file, you can transfer it to z/OS and expand its cont ``` put .pax ``` + where: - `zowe-V.v.p` is a variable that indicates the name of the PAX file you downloaded. + * `zowe-V.v.p` + is a variable that indicates the name of the PAX file you downloaded. **Note:** When your terminal is connected to z/OS through FTP or SFTP, you can prepend commands with `l` to have them issued against your desktop. To list the contents of a directory on your desktop, type `lls` where `ls` lists contents of a directory on z/OS. @@ -67,9 +69,11 @@ After you download the PAX file, you can transfer it to z/OS and expand its cont pax -ppx -rf .pax ``` - Where _zowe-V.v.p_ is a variable that indicates the name of the PAX file you downloaded. When extracting the Zowe convenience build, you must always include the `-ppx` argument that preserves extended attributes. + where: + * `zowe-V.v.p` + is a variable that indicates the name of the PAX file you downloaded. When extracting the Zowe convenience build, you must always include the `-ppx` argument that preserves extended attributes. - This will expand to a file structure similar to the following one. + This command expands to a file structure similar to the following one: ``` /bin @@ -80,7 +84,7 @@ After you download the PAX file, you can transfer it to z/OS and expand its cont This is the Zowe runtime directory and is referred to as `` throughout this documentation. - **Note:** Zowe version 1 had a script `zowe-install.sh` that created a separate Zowe runtime directory from the expanded contents of the Zowe PAX file. Zowe v2 no longer has this step. **In Zowe v2, the contents of the expanded Zowe PAX file are the Zowe runtime directory.** + **Note:** Zowe version 1 had a script `zowe-install.sh` that created a separate Zowe runtime directory from the expanded contents of the Zowe PAX file. Zowe v2 no longer has this step. **In Zowe v2, and Zowe v3 the contents of the expanded Zowe PAX file are the Zowe runtime directory.** ## Step 3: (Optional) Add the `zwe` command to your PATH @@ -92,7 +96,7 @@ export PATH=${PATH}:/bin `` should be replaced with your real Zowe runtime directory path. This will update the `PATH` for the current shell. To make this update persistent, you can add the line to your `~/.profile` file, or the `~/.bashProfile` file if you are using a bash shell. To make this update system wide, you can update the `/etc/.profile` file. Once the PATH is updated, you can execute the `zwe` command from any USS directory. For the remainder of the documentation when `zwe` command is referenced, it is assumed that it has been added to your `PATH`. -The `zwe` command has built in help that can be retrieved with the `-h` suffix. For example, type `zwe -h` to display all of the supported commands. These are broken down into a number of sub-commands. +The `zwe` command has built in help that can be retrieved with the `-h` suffix. For example, type `zwe -h` to display all of the supported commands. These are broken down into a number of sub-commands: ``` zwe -h @@ -216,4 +220,4 @@ Copy components/zss/LOADLIB/ZWESAUX to IBMUSER.ZWEV2.SZWEAUTH ## Next steps -You successfully installed Zowe from the convenience build! However, before you start Zowe, you must complete several required configurations. Next, go to [Initialize the z/OS system and permissions](initialize-zos-system.md) to initialize your z/OS system for Zowe first. +You successfully installed Zowe from the convenience build! However, before you start Zowe, you must complete several required configurations. The next step is to [Initialize the z/OS system and permissions](initialize-zos-system.md) for Zowe. From 18594a0e8a3f88b2bfc99ffe44afba5780a7182a Mon Sep 17 00:00:00 2001 From: Martin Zeithaml Date: Mon, 18 Nov 2024 12:31:00 +0100 Subject: [PATCH 05/14] Table of members Signed-off-by: Martin Zeithaml --- .../install-zowe-zos-convenience-build.md | 59 ++++++++++++++----- 1 file changed, 45 insertions(+), 14 deletions(-) diff --git a/docs/user-guide/install-zowe-zos-convenience-build.md b/docs/user-guide/install-zowe-zos-convenience-build.md index d3f87d0074..ab04419345 100644 --- a/docs/user-guide/install-zowe-zos-convenience-build.md +++ b/docs/user-guide/install-zowe-zos-convenience-build.md @@ -84,7 +84,7 @@ After you download the PAX file, you can transfer it to z/OS and expand its cont This is the Zowe runtime directory and is referred to as `` throughout this documentation. - **Note:** Zowe version 1 had a script `zowe-install.sh` that created a separate Zowe runtime directory from the expanded contents of the Zowe PAX file. Zowe v2 no longer has this step. **In Zowe v2, and Zowe v3 the contents of the expanded Zowe PAX file are the Zowe runtime directory.** + **Note:** In Zowe v2, and Zowe v3 the contents of the expanded Zowe PAX file are the Zowe runtime directory. ## Step 3: (Optional) Add the `zwe` command to your PATH @@ -148,19 +148,49 @@ SZWELOAD | Executable utilities library | ANY | U | PDSE | U | 0 | 15 | N/A The `SZWESAMP` data set contains the following members. -Member name | Purpose ----|--- -ZWESECUR | JCL member to configure z/OS user IDs and permissions required to run Zowe -ZWENOSEC | JCL member to undo the configuration steps performed in ZWESECUR and revert z/OS environment changes. -ZWEKRING | JCL member to configure a z/OS keyring containing the Zowe certificate -ZWENOKYR | JCL member to undo the configuration steps performed in ZWEKRING -ZWESLSTC | JCL to start Zowe -ZWEXMSTC | JCL to start the Zowe cross memory server -ZWESIP00 | Parmlib member for the cross memory server -ZWESASTC | Started task JCL for the cross memory Auxiliary server -ZWESIPRG | Console commands to APF authorize the cross memory server load library -ZWESISCH | PPT entries required by Cross memory server and its Auxiliary address spaces to run in Key(4) -ZWECSVSM | JCL Member to create the VSAM data set for the caching service +Member name | Type | Purpose +---|---|--- +ZWECSRVS | JCL | Removes the VSAM data set for the Caching Service +ZWECSVSM | JCL | Creates the VSAM data set for the Caching Service +ZWEGENER | JCL | Generates JCL templates to configure Zowe +ZWEIACF | JCL | Defines security permits for ACF2 +ZWEIACFZ | JCL | Creates the ACF2 Zowe resource class +ZWEIAPF | JCL | Set APF for the required datasets +ZWEIAPF2| JCL | Set APF for the required datasets +ZWEIKRA1 | JCL | Defines ACF2 key ring and certificates +ZWEIKRA2 | JCL | Defines ACF2 key ring and certificates +ZWEIKRA3 | JCL | Defines ACF2 key ring and certificates +ZWEIKRR1 | JCL | Defines RACF key ring and certificates +ZWEIKRR2 | JCL | Defines RACF key ring and certificates +ZWEIKRR3 | JCL | Defines RACF key ring and certificates +ZWEIKRT1 | JCL | Defines TSS key ring and certificates +ZWEIKRT2 | JCL | Defines TSS key ring and certificates +ZWEIKRT3 | JCL | Defines TSS key ring and certificates +ZWEIMVS | JCL | Creates datasets used by a Zowe instance +ZWEIMVS2 | JCL | Creates the load library (expected to be APF) +ZWEINSTL | JCL | Creates and copies basic installation datasets and members +ZWEIRAC | JCL | Defines security permits for RACF +ZWEIRACZ | JCL | Creates the RACF Zowe resource class +ZWEISTC | JCL | Adds `PROCLIB` members +ZWEITSS | JCL | Defines security permits for TSS +ZWEITSSZ | JCL | Creates the TSS Zowe resource class +ZWEKRING | JCL | Defines key ring and certificates +ZWENOKRA | JCL | Removes key ring and certificates for ACF2 +ZWENOKRR | JCL | Removes key ring and certificates for RACF +ZWENOKRT | JCL | Removes key ring and certificates for TSS +ZWENOKYR | JCL | Removes key ring and certificates +ZWENOSEC | JCL | Defines security permits +ZWERMVS | JCL | Removes datasets used by a Zowe instance +ZWERMVS2 | JCL | Removes the APF load library +ZWERSTC | JCL | Removes `PROCLIB` members +ZWESASTC | JCL | Starts the Zowe Auxiliary server used by Cross memory server +ZWESECKG | JCL | Sample program which generates a secret key for the PKCS#11 token +ZWESECUR | JCL | Defines security permits for Zowe +ZWESIPRG | Commands | Console commands to APF authorize the cross memory server load library +ZWESIP00 | PARMLIB | Member for the cross memory server +ZWESISCH | PPT | Defines entries required by Cross memory server and its Auxiliary address spaces to run in Key(4) +ZWESISTC | JCL | Starts the Zowe Cross memory server +ZWESLSTC | JCL | Starts the Zowe The `SZWEAUTH` data set is a load library containing the following members. @@ -169,6 +199,7 @@ Member name | Purpose ZWELNCH | The Zowe launcher that controls the startup, restart and shutdown of Zowe's address spaces ZWESIS01 | Load module for the cross memory server ZWESAUX | Load module for the cross memory server's auxiliary address space +ZWESISDL | ZIS Dynamic Plug-in The `SZWEEXEC` data set contains few utilities used by Zowe. From 5ef0f29987057bf34f91b886a5c3940ab597df2b Mon Sep 17 00:00:00 2001 From: Martin Zeithaml Date: Mon, 18 Nov 2024 15:13:31 +0100 Subject: [PATCH 06/14] Minor changes Signed-off-by: Martin Zeithaml --- .../install-zowe-zos-convenience-build.md | 40 ++++++++++++------- 1 file changed, 25 insertions(+), 15 deletions(-) diff --git a/docs/user-guide/install-zowe-zos-convenience-build.md b/docs/user-guide/install-zowe-zos-convenience-build.md index ab04419345..08f23a83ad 100644 --- a/docs/user-guide/install-zowe-zos-convenience-build.md +++ b/docs/user-guide/install-zowe-zos-convenience-build.md @@ -17,7 +17,7 @@ Complete the following steps to install the Zowe runtime. ## Step 1: Obtain the convenience build 1. To download the PAX file, open your web browser on the [Zowe Download](https://www.zowe.org/download.html) website. -2. Navigate to **Zowe V2 Preview** -> **Convenience build** section, and select the button to download the v2 convenience build. +2. Navigate to **Zowe V3** -> **Zowe 3.v.p z/OS Convenience build** section, and select the button to download the v3 convenience build. ## Step 2: Transfer the convenience build to USS and expand it @@ -59,6 +59,12 @@ After you download the PAX file, you can transfer it to z/OS and expand its cont **Note:** When your terminal is connected to z/OS through FTP or SFTP, you can prepend commands with `l` to have them issued against your desktop. To list the contents of a directory on your desktop, type `lls` where `ls` lists contents of a directory on z/OS. + :::tip + You can simplify `sftp` usage for existing directory: + ``` + echo 'put .pax' | sftp userID@ip.of.zos.box:/path/to/zowe/runtime + ``` + After the PAX file has sucessfully transferred, exit your `sftp` or `ftp` session. 1. Open a USS shell to expand the PAX file. This can either be an ssh terminal, OMVS, iShell, or any other z/OS unix system services command environment. @@ -94,23 +100,27 @@ The `zwe` command is provided in the `/bin` directory. You can opti export PATH=${PATH}:/bin ``` -`` should be replaced with your real Zowe runtime directory path. This will update the `PATH` for the current shell. To make this update persistent, you can add the line to your `~/.profile` file, or the `~/.bashProfile` file if you are using a bash shell. To make this update system wide, you can update the `/etc/.profile` file. Once the PATH is updated, you can execute the `zwe` command from any USS directory. For the remainder of the documentation when `zwe` command is referenced, it is assumed that it has been added to your `PATH`. +`` should be replaced with your real Zowe runtime directory path. This will update the `PATH` for the current shell. To make this update persistent, you can add the line to your `~/.profile` file, or the `~/.bashProfile` file if you are using a bash shell. To make this update system wide, you can update the `/etc/.profile` file. Once the `PATH` is updated, you can execute the `zwe` command from any USS directory. For the remainder of the documentation when `zwe` command is referenced, it is assumed that it has been added to your `PATH`. -The `zwe` command has built in help that can be retrieved with the `-h` suffix. For example, type `zwe -h` to display all of the supported commands. These are broken down into a number of sub-commands: +The `zwe` command has built in help that can be retrieved with the `-h` option. For example, type `zwe -h` to display all of the supported commands. These are broken down into a number of sub-commands: ``` zwe -h ... Available sub-command(s): - - certificate - - components - - init - - install - - internal - - sample - - start - - stop - - version + - certificate + - components + - config + - diagnose + - init + - install + - internal + - migrate + - sample + - start + - stop + - support + - version ``` ## Step 4: Copy the zowe.yaml configuration file to preferred location @@ -120,7 +130,7 @@ Copy the template file `/example-zowe.yaml` file to a new location, When you execute the `zwe` command, the `-c` argument is used to pass the location of a `zowe.yaml` file. :::tip -To avoid passing `--config` or `-c` to every `zwe` commands, you can define `ZWE_CLI_PARAMETER_CONFIG` environment variable points to location of zowe.yaml. +To avoid passing `--config` or `-c` to every `zwe` commands, you can define `ZWE_CLI_PARAMETER_CONFIG` environment variable pointing to location of `zowe.yaml`. For example, after defining @@ -137,7 +147,7 @@ After you extract the Zowe convenience build, you can run the [`zwe install` com ### About the MVS data sets -Zowe includes a number of files that are stored in the following three data sets. See the following table for the storage requirements. +Zowe includes a number of files that are stored in the following data sets. See the following table for the storage requirements. Library DDNAME | Member Type | Target Volume | Type | Org | RECFM | LRECL | No. of 3390 Trks | No. of DIR Blks ---|---|---|---|---|---|---|---|--- @@ -218,7 +228,7 @@ zowe: ``` To create and install the MVS data sets, use the command `zwe install`. -1. In a USS shell, execute the command `zwe install -c /path/to/zowe.yaml`. This creates the three data sets and copy across their content. +1. In a USS shell, execute the command `zwe install -c /path/to/zowe.yaml`. This creates the data sets and copy across their content. 2. If the data sets already exist, specify `--allow-overwritten`. 3. To see the full list of parameters, execute the command `zwe install -h`. From b8f7c931a43b9d64a4077f7cd0642145f832f758 Mon Sep 17 00:00:00 2001 From: Martin Zeithaml Date: Mon, 18 Nov 2024 15:16:11 +0100 Subject: [PATCH 07/14] Indentation update Signed-off-by: Martin Zeithaml --- .../install-zowe-zos-convenience-build.md | 26 +++++++++---------- 1 file changed, 13 insertions(+), 13 deletions(-) diff --git a/docs/user-guide/install-zowe-zos-convenience-build.md b/docs/user-guide/install-zowe-zos-convenience-build.md index 08f23a83ad..d8cbf32d31 100644 --- a/docs/user-guide/install-zowe-zos-convenience-build.md +++ b/docs/user-guide/install-zowe-zos-convenience-build.md @@ -108,19 +108,19 @@ The `zwe` command has built in help that can be retrieved with the `-h` option. zwe -h ... Available sub-command(s): - - certificate - - components - - config - - diagnose - - init - - install - - internal - - migrate - - sample - - start - - stop - - support - - version + - certificate + - components + - config + - diagnose + - init + - install + - internal + - migrate + - sample + - start + - stop + - support + - version ``` ## Step 4: Copy the zowe.yaml configuration file to preferred location From b02895e7f91fdbcb445d9a528dc8c6deb4c4180d Mon Sep 17 00:00:00 2001 From: Timothy Johnson Date: Mon, 18 Nov 2024 09:36:27 -0500 Subject: [PATCH 08/14] Append PR number to artifact name for preview builds Signed-off-by: Timothy Johnson --- .github/workflows/build-docs.yml | 6 ++---- .github/workflows/deploy-preview.yml | 8 +++++--- 2 files changed, 7 insertions(+), 7 deletions(-) diff --git a/.github/workflows/build-docs.yml b/.github/workflows/build-docs.yml index 335faa4f66..fd97992520 100644 --- a/.github/workflows/build-docs.yml +++ b/.github/workflows/build-docs.yml @@ -74,14 +74,12 @@ jobs: - name: Compress Build Archive if: ${{ steps.deploy.conclusion == 'skipped' }} - run: | - echo "PR_NUMBER=${{ github.event.pull_request.number }}" > build/.env - tar --remove-files --zstd -cf build.tar.zst build + run: tar --remove-files --zstd -cf build.tar.zst build - name: Upload Build Artifact if: ${{ steps.deploy.conclusion == 'skipped' }} uses: actions/upload-artifact@v3 with: - name: preview-build + name: preview-build-${{ github.event.pull_request.number }} path: build.tar.zst retention-days: 1 diff --git a/.github/workflows/deploy-preview.yml b/.github/workflows/deploy-preview.yml index 4119744de3..e539c340b8 100644 --- a/.github/workflows/deploy-preview.yml +++ b/.github/workflows/deploy-preview.yml @@ -23,14 +23,16 @@ jobs: with: workflow: build-docs.yml run_id: ${{ github.event.workflow_run.id }} - name: preview-build + name: "preview-build-\\d+" + name_is_regexp: true if_no_artifact_found: warn - name: Extract Build Archive if: ${{ steps.download-artifact.outputs.found_artifact == 'true' }} run: | - tar -xf build.tar.zst && rm build.tar.zst - cat build/.env >> "$GITHUB_ENV" && rm build/.env + artifactName=$(echo '${{ steps.download-artifact.outputs.artifacts }}' | jq -r '.[0].name') + tar -xf $artifactName/build.tar.zst && rm $artifactName/build.tar.zst + echo "PR_NUMBER=$(echo $artifactName | awk -F'-' '{print $NF}')" >> "$GITHUB_ENV" - name: Deploy to Netlify id: deploy From 898360fa186ef4d19fc816e9268cfe4efe415bf8 Mon Sep 17 00:00:00 2001 From: Timothy Johnson Date: Mon, 18 Nov 2024 13:02:48 -0500 Subject: [PATCH 09/14] Test storing PR number as TAR label Signed-off-by: Timothy Johnson --- .github/workflows/build-docs.yml | 16 ++++++++-------- .github/workflows/deploy-preview.yml | 13 ++++++------- 2 files changed, 14 insertions(+), 15 deletions(-) diff --git a/.github/workflows/build-docs.yml b/.github/workflows/build-docs.yml index fd97992520..6b1df8d284 100644 --- a/.github/workflows/build-docs.yml +++ b/.github/workflows/build-docs.yml @@ -36,14 +36,14 @@ jobs: # https://github.com/actions/checkout/issues/520#issuecomment-1320838255 fetch-depth: 2147483647 - - name: Use Node.js LTS - uses: actions/setup-node@v3 + - name: Use Node.js 20 + uses: actions/setup-node@v4 with: - node-version: 18 + node-version: 20 cache: 'npm' - name: Cache Webpack Build - uses: actions/cache@v3 + uses: actions/cache@v4 env: TAR_OPTIONS: "--remove-files" with: @@ -59,7 +59,7 @@ jobs: - name: Deploy to Netlify id: deploy if: ${{ github.event_name == 'push' || github.event.pull_request.head.repo.full_name == github.repository }} - uses: nwtgck/actions-netlify@v2 + uses: nwtgck/actions-netlify@v3 with: publish-dir: build production-branch: master @@ -74,12 +74,12 @@ jobs: - name: Compress Build Archive if: ${{ steps.deploy.conclusion == 'skipped' }} - run: tar --remove-files --zstd -cf build.tar.zst build + run: tar --label=${{ github.event.pull_request.number }} --remove-files --zstd -cf build.tar.zst build - name: Upload Build Artifact if: ${{ steps.deploy.conclusion == 'skipped' }} - uses: actions/upload-artifact@v3 + uses: actions/upload-artifact@v4 with: - name: preview-build-${{ github.event.pull_request.number }} + name: preview-build path: build.tar.zst retention-days: 1 diff --git a/.github/workflows/deploy-preview.yml b/.github/workflows/deploy-preview.yml index e539c340b8..fc5ae916dc 100644 --- a/.github/workflows/deploy-preview.yml +++ b/.github/workflows/deploy-preview.yml @@ -19,25 +19,24 @@ jobs: steps: - name: Download Build Artifact id: download-artifact - uses: dawidd6/action-download-artifact@v2 + uses: dawidd6/action-download-artifact@v6 with: workflow: build-docs.yml run_id: ${{ github.event.workflow_run.id }} - name: "preview-build-\\d+" - name_is_regexp: true + name: preview-build if_no_artifact_found: warn - name: Extract Build Archive if: ${{ steps.download-artifact.outputs.found_artifact == 'true' }} run: | - artifactName=$(echo '${{ steps.download-artifact.outputs.artifacts }}' | jq -r '.[0].name') - tar -xf $artifactName/build.tar.zst && rm $artifactName/build.tar.zst - echo "PR_NUMBER=$(echo $artifactName | awk -F'-' '{print $NF}')" >> "$GITHUB_ENV" + tar -xf build.tar.zst + echo "PR_NUMBER=$(tar --test-label -f build.tar.zst)" >> "$GITHUB_ENV" + rm build.tar.zst - name: Deploy to Netlify id: deploy if: ${{ steps.download-artifact.outputs.found_artifact == 'true' }} - uses: nwtgck/actions-netlify@v2 + uses: nwtgck/actions-netlify@v3 with: publish-dir: build production-deploy: false From 62108e78168a6ce6a64cb0139610939f363bc75c Mon Sep 17 00:00:00 2001 From: Timothy Johnson Date: Mon, 18 Nov 2024 18:56:06 -0500 Subject: [PATCH 10/14] Update deploy-preview.yml Signed-off-by: Timothy Johnson --- .github/workflows/deploy-preview.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/workflows/deploy-preview.yml b/.github/workflows/deploy-preview.yml index fc5ae916dc..50dca1ec48 100644 --- a/.github/workflows/deploy-preview.yml +++ b/.github/workflows/deploy-preview.yml @@ -30,7 +30,7 @@ jobs: if: ${{ steps.download-artifact.outputs.found_artifact == 'true' }} run: | tar -xf build.tar.zst - echo "PR_NUMBER=$(tar --test-label -f build.tar.zst)" >> "$GITHUB_ENV" + printf "PR_NUMBER=%d\n" "$(tar --test-label -f build.tar.zst)" >> "$GITHUB_ENV" rm build.tar.zst - name: Deploy to Netlify From 2518fc7dbfc5340ed6ea8495a6509ddee7aee252 Mon Sep 17 00:00:00 2001 From: "dependabot[bot]" <49699333+dependabot[bot]@users.noreply.github.com> Date: Tue, 19 Nov 2024 01:32:24 +0000 Subject: [PATCH 11/14] Bump cross-spawn from 7.0.3 to 7.0.6 Bumps [cross-spawn](https://github.com/moxystudio/node-cross-spawn) from 7.0.3 to 7.0.6. - [Changelog](https://github.com/moxystudio/node-cross-spawn/blob/master/CHANGELOG.md) - [Commits](https://github.com/moxystudio/node-cross-spawn/compare/v7.0.3...v7.0.6) --- updated-dependencies: - dependency-name: cross-spawn dependency-type: indirect ... Signed-off-by: dependabot[bot] --- package-lock.json | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/package-lock.json b/package-lock.json index 5f12b50837..edd7f276a9 100644 --- a/package-lock.json +++ b/package-lock.json @@ -6479,9 +6479,9 @@ } }, "node_modules/cross-spawn": { - "version": "7.0.3", - "resolved": "https://registry.npmjs.org/cross-spawn/-/cross-spawn-7.0.3.tgz", - "integrity": "sha512-iRDPJKUPVEND7dHPO8rkbOnPpyDygcDFtWjpeWNCgy8WP2rXcxXL8TskReQl6OrB2G7+UJrags1q15Fudc7G6w==", + "version": "7.0.6", + "resolved": "https://registry.npmjs.org/cross-spawn/-/cross-spawn-7.0.6.tgz", + "integrity": "sha512-uV2QOWP2nWzsy2aMp8aRibhi9dlzF5Hgh5SHaB9OiTGEyDTiJJyx0uy51QXdyWbtAHNua4XJzUKca3OzKUd3vA==", "dependencies": { "path-key": "^3.1.0", "shebang-command": "^2.0.0", From 0b2d38bc412ccadfba6a71991867d46a8ea8e90d Mon Sep 17 00:00:00 2001 From: Martin Zeithaml Date: Tue, 19 Nov 2024 12:56:00 +0100 Subject: [PATCH 12/14] Minor updates Signed-off-by: Martin Zeithaml --- docs/user-guide/install-zowe-zos-convenience-build.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/docs/user-guide/install-zowe-zos-convenience-build.md b/docs/user-guide/install-zowe-zos-convenience-build.md index d8cbf32d31..e45cb1d15d 100644 --- a/docs/user-guide/install-zowe-zos-convenience-build.md +++ b/docs/user-guide/install-zowe-zos-convenience-build.md @@ -64,6 +64,7 @@ After you download the PAX file, you can transfer it to z/OS and expand its cont ``` echo 'put .pax' | sftp userID@ip.of.zos.box:/path/to/zowe/runtime ``` + ::: After the PAX file has sucessfully transferred, exit your `sftp` or `ftp` session. @@ -147,7 +148,7 @@ After you extract the Zowe convenience build, you can run the [`zwe install` com ### About the MVS data sets -Zowe includes a number of files that are stored in the following data sets. See the following table for the storage requirements. +Zowe includes a number of files that are stored in the various data sets. See the following table for the storage requirements. Library DDNAME | Member Type | Target Volume | Type | Org | RECFM | LRECL | No. of 3390 Trks | No. of DIR Blks ---|---|---|---|---|---|---|---|--- From c4cc96ab7dada66b77357113e79766e7fcbb6dbc Mon Sep 17 00:00:00 2001 From: anaxceron Date: Tue, 19 Nov 2024 10:44:01 -0600 Subject: [PATCH 13/14] clarification post docs-staging merge Signed-off-by: anaxceron --- release-handbook/major_release_workflow.md | 1 + 1 file changed, 1 insertion(+) diff --git a/release-handbook/major_release_workflow.md b/release-handbook/major_release_workflow.md index 802a58680b..5fb12d65ea 100644 --- a/release-handbook/major_release_workflow.md +++ b/release-handbook/major_release_workflow.md @@ -162,6 +162,7 @@ For major Zowe releases, follow the process outlined here. 10. Publish the staged doc to the live site: - Change the PR you opened in Step 6 to **Ready for review** mode to merge the new branch into the `docs-staging` branch. - All checks **must** pass before merging. If any checks fail, troubleshoot with Doc Squad members or developers well familiar with the `docs-site` repo to resolve. + - Any edits to the new major release doc now needs to be done in the `docs-staging` branch. - After the new branch is merged to `docs-staging`, create a PR to merge `docs-staging` into the `master` branch. - In your PR, do the following: - Add the Zowe release engineer to the reviewer list. From f5d2747958289894a5c28677688d89f51f27f546 Mon Sep 17 00:00:00 2001 From: Andrew Jandacek Date: Wed, 20 Nov 2024 11:02:42 +0100 Subject: [PATCH 14/14] fix link Signed-off-by: Andrew Jandacek --- docs/user-guide/install-zowe-zos-convenience-build.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/user-guide/install-zowe-zos-convenience-build.md b/docs/user-guide/install-zowe-zos-convenience-build.md index e45cb1d15d..562ea55277 100644 --- a/docs/user-guide/install-zowe-zos-convenience-build.md +++ b/docs/user-guide/install-zowe-zos-convenience-build.md @@ -1,10 +1,10 @@ # Installing the z/OS Build via Convenience Build (PAX file) -You install the Zowe™ convenience build by obtaining a PAX file and using this to create the Zowe runtime environment. +You can install the Zowe™ convenience build by obtaining a PAX file which is used to create the Zowe runtime environment. ## Introduction -The Zowe installation file for Zowe z/OS components is distributed as a PAX file that contains the runtimes and the scripts to install and launch the z/OS runtime. You must obtain the PAX file and transfer it to z/OS first. Then, to install, configure and start Zowe, you use the `zwe` command. This command defines help messages, logging options, and more. For details about how to use this command, see the [ZWE Server Command Reference](../appendix/zwe_server_command_reference/zwe/zwe.md). +The Zowe installation file for Zowe z/OS components is distributed as a PAX file that contains the runtimes and the scripts to install and launch the z/OS runtime. You must obtain the PAX file and transfer it to z/OS first. Then, to install, configure, and start Zowe, you use the `zwe` command. This command defines help messages, logging options, and more. For details about how to use this command, see the [ZWE Server Command Reference](../appendix/zwe_server_command_reference/zwe/zwe.md). The configuration data that is read by the `zwe` command are stored in a YAML configuration file named `zowe.yaml`. You modify the `zowe.yaml` file based on your environment. @@ -262,4 +262,4 @@ Copy components/zss/LOADLIB/ZWESAUX to IBMUSER.ZWEV2.SZWEAUTH ## Next steps -You successfully installed Zowe from the convenience build! However, before you start Zowe, you must complete several required configurations. The next step is to [Initialize the z/OS system and permissions](initialize-zos-system.md) for Zowe. +You successfully installed Zowe from the convenience build! However, before you start Zowe, you must complete several required configurations. The next step is [Initializing Zowe z/OS runtime](./configure-zowe-runtime.md).