adding new Upgrade section to docs site#5085

Open

anaxceron wants to merge 55 commits into

docs-stagingfrom

anax-v3.6-newupgradesection-docs

anaxceron commented Jul 13, 2026 •

edited

Loading

Collaborator

Describe your pull request here: Adding a new section titled Upgrade to the site's top nav bar.

List the file(s) included in this PR: several.md

After creating the PR, follow the instructions in the comments.


          adding new Upgrade section to docs site

8bb0f7c

Signed-off-by: anaxceron <ana.ceron@broadcom.com>

anaxceron requested a review from janan07

July 13, 2026 20:08

anaxceron self-assigned this

anaxceron added area: docs release: V3 labels

github-actions Bot commented Jul 13, 2026

😺 Thank you for creating this PR! To publish your content to Zowe Docs, follow these steps.

Add the label review: sme if an SME needs to check your content.
Identify your content topic with a label. (Examples: area: apiml, area: cli, area: install and config, etc.)
Specify the major Zowe release(s) for your content. (Examples: release: V1, release: V2, release: V3)
- If adding content that needs to be removed from V3 documentation, add the V3 N/A tag.
Link any Doc Issues related to this PR.
Fix broken links found in your content areas.
Notify the SME to review this PR (if applicable).
Merge to the master branch if your PR updates content that is on the live site. Merge to docs-staging if your PR updates content for a future release.

github-actions Bot commented Jul 13, 2026 •

edited

Loading

🚀 Deployed on https://6a6237ba827019b748825215--zowe-docs-master.netlify.app

github-actions Bot temporarily deployed to pull request

July 13, 2026 20:15

Inactive


          Indentation fix

f4bd5a0

The indentation was ok, but we are usually using two spaces in our examples or snippets.

Signed-off-by: Martin Zeithaml <66114686+Martin-Zeithaml@users.noreply.github.com>

github-actions Bot temporarily deployed to pull request

July 14, 2026 06:15

Inactive


          fix titles Uprading/Migrating

731ce83

Signed-off-by: Andrew Jandacek <andrew.jandacek@broadcom.com>

github-actions Bot temporarily deployed to pull request

July 14, 2026 10:53

Inactive


          reorder nav bar to correct location of Upgrade section

9af1cb0

Signed-off-by: Andrew Jandacek <andrew.jandacek@broadcom.com>

github-actions Bot temporarily deployed to pull request

July 14, 2026 14:33

Inactive


          correcting location of Update section in the sidebar

a80b16e

Signed-off-by: anaxceron <ana.ceron@broadcom.com>

anaxceron commented

View reviewed changes

docusaurus.config.js Outdated

github-actions Bot temporarily deployed to pull request

July 14, 2026 17:01

Inactive

janan07 requested review from RASakach and balhar-jakub

July 15, 2026 15:23

balhar-jakub commented Jul 16, 2026

Member

I really like the location in the top bar, it makes it so clear on where to go and where to put additional items related to upgrading.


          update banner with new location of zowe-v3-migration / fix terminology

c07dba3

Signed-off-by: Andrew Jandacek <andrew.jandacek@broadcom.com>

github-actions Bot temporarily deployed to pull request

July 16, 2026 08:22

Inactive

janan07 added 2 commits

July 17, 2026 13:48


          fix macro

86e6753

Signed-off-by: Andrew Jandacek <andrew.jandacek@broadcom.com>


          Merge branch 'docs-staging' into anax-v3.6-newupgradesection-docs

cc6530b

Signed-off-by: Andrew Jandacek <andrew.jandacek@broadcom.com>

github-actions Bot temporarily deployed to pull request

July 17, 2026 12:04

Inactive

janan07 added 5 commits

July 17, 2026 14:07


          test commit

949575d

Signed-off-by: Andrew Jandacek <andrew.jandacek@broadcom.com>


          Merge branch 'anax-v3.6-newupgradesection-docs' of https://github.com…

37f2198

…/zowe/docs-site into anax-v3.6-newupgradesection-docs


          Update migrate-extensions.md

639f0db


          change file name and file location to under Upgrade

bae4185

Signed-off-by: Andrew Jandacek <andrew.jandacek@broadcom.com>


          fix sidebar

8623dbf

Signed-off-by: Andrew Jandacek <andrew.jandacek@broadcom.com>


          add note that original upgrade file is being deprecated and replace w…

c6fa5f8

…ith upgrading-zowe.md

Signed-off-by: Andrew Jandacek <andrew.jandacek@broadcom.com>

github-actions Bot temporarily deployed to pull request

July 22, 2026 10:58

Inactive

janan07 added 2 commits

July 22, 2026 13:47


          update test in backout topic

3fcf89c

Signed-off-by: Andrew Jandacek <andrew.jandacek@broadcom.com>


          fix formatting

b26d1bc

Signed-off-by: Andrew Jandacek <andrew.jandacek@broadcom.com>

github-actions Bot temporarily deployed to pull request

July 22, 2026 11:55

Inactive

janan07 added 5 commits

July 22, 2026 14:01


          move apiml single service deploy under upgrade

e647efb

Signed-off-by: Andrew Jandacek <andrew.jandacek@broadcom.com>


          add upgrade to single service deployment of API ML to Upgrade

bc44305

Signed-off-by: Andrew Jandacek <andrew.jandacek@broadcom.com>


          fix syntax

12a122d

Signed-off-by: Andrew Jandacek <andrew.jandacek@broadcom.com>


          fix syntax

7c1ea33

Signed-off-by: Andrew Jandacek <andrew.jandacek@broadcom.com>


          fix syntax

33886e8

Signed-off-by: Andrew Jandacek <andrew.jandacek@broadcom.com>

github-actions Bot temporarily deployed to pull request

July 22, 2026 13:11

Inactive

janan07 added 2 commits

July 22, 2026 15:28


          fix sidebar and docusaurus.config.js

f5df15b

Signed-off-by: Andrew Jandacek <andrew.jandacek@broadcom.com>


          fix sidebar

e647bf7

Signed-off-by: Andrew Jandacek <andrew.jandacek@broadcom.com>

balhar-jakub reviewed

View reviewed changes

docs/upgrade/backout-zos.md Outdated

docs/upgrade/upgrade-zos.md Outdated

docs/upgrade/upgrading-zowe.md Outdated


          fix typo

b1dd7f6

Signed-off-by: Andrew Jandacek <andrew.jandacek@broadcom.com>

github-actions Bot temporarily deployed to pull request

July 23, 2026 08:32

Inactive

janan07 added 4 commits

July 23, 2026 16:00


          refactor Upgrading dor no downtime for consistency with Zowe Docs sta…

f7f7c36

…ndards

Signed-off-by: Andrew Jandacek <andrew.jandacek@broadcom.com>


          update HA topic and add to sidebar

a54aea9

Signed-off-by: Andrew Jandacek <andrew.jandacek@broadcom.com>


          update numbering

721a130

Signed-off-by: Andrew Jandacek <andrew.jandacek@broadcom.com>


          update sidebars.js

2c42655

Signed-off-by: Andrew Jandacek <andrew.jandacek@broadcom.com>

github-actions Bot temporarily deployed to pull request

July 23, 2026 14:53

Inactive


          fix link

19d2937

Signed-off-by: Andrew Jandacek <andrew.jandacek@broadcom.com>

github-actions Bot temporarily deployed to pull request

July 23, 2026 15:15

Inactive


          add tip about zero downtime

da36046

Signed-off-by: Andrew Jandacek <andrew.jandacek@broadcom.com>

github-actions Bot temporarily deployed to pull request

July 23, 2026 15:31

Inactive


          fix level two headers for clarity

c6604db

Signed-off-by: Andrew Jandacek <andrew.jandacek@broadcom.com>

github-actions Bot temporarily deployed to pull request

July 23, 2026 15:48

Inactive

anaxceron commented Jul 23, 2026

Collaborator Author

Not sure where this is coming from, but I'm seeing two Upgrading Zowe headers in the sidebar:

anaxceron commented Jul 23, 2026

Collaborator Author

@janan07 -- left review comments but didn't always make comments every time I thought they were applicable b/c that would've felt too repetitive for both of us.

Consolidating my thoughts here:

Overall, it seems to me like this is focused on server-side upgrades. I don't think that's always clear in all of the articles here. For example, when we have an article titled Upgrading Zowe, what part of Zowe are we talking about? I don't think I saw much client-side content in there, so I think we should clarify this, or expand the scope a little in this article.

Should we be adding instructions on how to upgrade all components to this new Upgrade section? For example, Updating Zowe CLI and Zowe CLI plug-ins is currently in the Install section of the site. Should it stay there or be relocated? I will be asking this to the Onboarding squad tomorrow.

Comments on style points I saw across this PR:

All headers should use sentence-style capitalization
data sets not datasets
file names should be in backticks (such as zowe.yaml)
no Latin abbreviations: e.g. -> for example
may -> might
Personally, I try to qualify anything in backticks. For example: Use the zowe.yaml configuration file to save all your custom settings. Use the funnyStuff property in the haHaha profile in the zowe.config.json file to add your joke value. Etc.
Some of the customized admonition headers included colons. We should get rid of those colons so that all the admonition headers (custom and default) align w/ the docusaurus style.

I won't approve this PR until I get a better sense from the Onboarding discussion on what we're doing about client-vs-server side updgrade documentation. Lmk if you have questions. Thanks for all hard work here. Lots of good stuff.

anaxceron commented

View reviewed changes

docs/upgrade/backout-zos.md

		@@ -0,0 +1,15 @@
		# Backout to revert to a previous Zowe version

anaxceron Jul 23, 2026

Collaborator Author

Do we need the word "backout" here? I ask b/c I'm not sure if this could be a technical term I'm not aware of. If possible, would it be better to title this "Revert to a previous Zowe version"? Or "Downgrade to a previous Zowe version"?
We use "downgrade" elsewhere in the doc and it'd be nice to have the wording align:
Example 1

Example 2

Example 3

docs/upgrade/upgrading-zowe.md

+              * If you need to revert an upgrade later, follow the recovery procedure in [Backout to revert to older Zowe version](./backout-zos.md).
+              :::
+              ## Installation and Configuration Tasks

anaxceron Jul 23, 2026

Collaborator Author

Pls change to sentence-style capitalization, per the zowe style guide

docs/upgrade/upgrading-zowe.md


		To complete an upgrade, perform all tasks listed in the Installing section of the installation guide. However, you only need to complete selected tasks within the Configuration sections.

		Unless otherwise noted by an announcement or SMP/E HOLD statement, you do not need to update certificates, instance datasets, networking, or security rules during an upgrade. Using [Configuring Zowe via JCL](../user-guide/configuring-zowe-via-jcl.md) as an example, you can skip the following steps:

anaxceron Jul 23, 2026

Collaborator Author

data sets

docs/upgrade/upgrading-zowe.md

+              To complete an upgrade, perform all tasks listed in the **Installing** section of the installation guide. However, you only need to complete selected tasks within the **Configuration** sections.
+              Unless otherwise noted by an announcement or SMP/E HOLD statement, you do not need to update certificates, instance datasets, networking, or security rules during an upgrade. Using [Configuring Zowe via JCL](../user-guide/configuring-zowe-via-jcl.md) as an example, you can skip the following steps:
+              * Create Instance Data sets

anaxceron Jul 23, 2026

Collaborator Author

Why capitalize anything after "Create"?

docs/upgrade/upgrading-zowe.md

+              Unless otherwise noted by an announcement or SMP/E HOLD statement, you do not need to update certificates, instance datasets, networking, or security rules during an upgrade. Using [Configuring Zowe via JCL](../user-guide/configuring-zowe-via-jcl.md) as an example, you can skip the following steps:
+              * Create Instance Data sets
+              * Grant SAF permissions
+              * Keyring Tasks

anaxceron Jul 23, 2026

Collaborator Author

Should "tasks" be capitalized?

docs/upgrade/upgrade-to-single-service-apiml-deployment.md

               Before transitioning to the single-service model, verify that your z/OS environment meets the minimum standards for Zowe v3:
               * **Java**
               Must be upgraded to Java 17 or Java 21. Ensure the `java.home` parameter in your zowe.yaml points to the correct home location for one of these versions.

anaxceron Jul 23, 2026

Collaborator Author

backticks for zowe.yaml in both bullets?

docs/upgrade/upgrade-to-single-service-apiml-deployment.md

                 Set `components.gateway.apiml.security.auth.provider: saf`.
                 The certificate that is used for signing is found in `zowe.certificate.keystore.file`.
                 This configuration enables API ML to validate identities using SAF Direct APIs.

anaxceron Jul 23, 2026

Collaborator Author

Should Lines 38, 39, 40 be sub-bullets? Or numbered steps? Not sure what these lines mean, are they instructions? Some formatting might help clear things up.

docs/upgrade/upgrade-to-single-service-apiml-deployment.md


		## Restarting Zowe

		After completing the infrastructure refresh and mandatory cleanup, you can bring Zowe back online.

anaxceron Jul 23, 2026

Collaborator Author

"clean up"

docs/upgrade/migrate-from-convenience-build-to-pswi-smpe.md

+              Follow these steps to validate that you successfully migrated your Zowe installation.
 . Start the following Zowe Started Tasks (STCs):
                 * **ZWESISTC**

anaxceron Jul 23, 2026

Collaborator Author

Can we add more indentation to the sub-bullets in Step1 and Step 3 to help them easier to read/understand their structure w/in the steps of instructions?

docs/upgrade/migrate-from-convenience-build-to-pswi-smpe.md

    
              * Retain previous runtime datasets

              Use the following guidelines to maintain rollback readiness in the event of unexpected issues during your Zowe migration:

              * Retain previous runtime data sets

              * Keep backup copies of all JCLs and configuration members

anaxceron Jul 23, 2026

Collaborator Author

back-up

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

area: docs release: V3