[RHACS] [Docs] [rhacs-docs-main] ROX-33164: Fixing DITA errors in cloud_service/upgrading-cloud/upgrade-cloudsvc-roxctl.adoc

[agantony]

Version(s):
4.9+

Issue:
https://redhat.atlassian.net/browse/ROX-33164

Link to docs preview:

SME review: NA

Additional information:

• Cherrypick to:
  • rhacs-docs-4.10
  • rhacs-docs-4.9

[openshift-ci-robot]

@agantony: This pull request references ROX-33164 which is a valid jira issue.

Details

In response to this:

Version(s):
4.9+

Issue:
https://redhat.atlassian.net/browse/ROX-33164

Link to docs preview:

SME review: NA

Additional information:

• Cherrypick to:
  • rhacs-docs-4.10
  • rhacs-docs-4.9

Instructions for interacting with me using PR comments are available here. If you have questions or suggestions related to my behavior, please file an issue against the openshift-eng/jira-lifecycle-plugin repository.

[ocpdocs-previewbot]

🤖 Tue Sep 01 07:57:34 - Prow CI generated the docs preview:

https://112143--ocpdocs-pr.netlify.app/openshift-acs/latest/cloud_service/upgrading-cloud/upgrade-cloudsvc-roxctl.html
https://112143--ocpdocs-pr.netlify.app/openshift-acs/latest/upgrading/upgrade-roxctl.html

[agantony]

PR Review Summary

Changes Made

This PR addresses DITA compliance issues in the cloud service roxctl upgrade documentation. The changes reorganize upgrade-related content into properly structured modules, extract CLI upgrade and secured cluster upgrade procedures, and refine existing procedure content.

Scope: 9 files modified (1 assembly, 8 modules)

• Content restructuring: CLI and secured cluster upgrade extraction
• DITA compliance: Module organization and procedure refinement
• Line count: +57 lines added, -40 lines removed

Summary of Changes

File	Location	Changes	Before/After
cloud_service/upgrading-cloud/upgrade-cloudsvc-roxctl.adoc	Assembly file	Reorganized module includes, updated structure	18 lines added, 16 lines removed
modules/upgrade-roxctl-cli.adoc	Procedure module (new)	New module for roxctl CLI upgrade procedure	10 lines added
modules/upgrade-secured-clusters-cloud.adoc	Procedure module (new)	New module for secured cluster upgrade procedure	15 lines added
modules/migrating-sccs-during-the-manual-upgrade.adoc	Procedure module	Refactored SCC migration content	13 lines added, 20 lines removed
modules/install-roxctl-cli-linux.adoc	Procedure module	Fixed attribute reference	1 line added, 1 line removed
modules/install-roxctl-cli-macos.adoc	Procedure module	Fixed attribute reference	1 line added, 1 line removed
modules/uninstall-roxctl-cli.adoc	Procedure module	Added missing line break	1 line added
modules/update-other-images.adoc	Procedure module	Removed extraneous content	2 lines removed
modules/rhcos-enable-node-scan.adoc	Procedure module	Minor refinement	1 line added, 1 line removed

Key structural changes:

• Extracted roxctl CLI upgrade into dedicated procedure module
• Extracted secured cluster upgrade into dedicated procedure module
• Reorganized assembly to present upgrade workflow clearly
• Fixed attribute references in CLI installation modules

Navigation Guide - Review Changes

Step 1: Review Main Assembly Structure

• Open: Upgrade using roxctl
• Verify: Document flows from CLI upgrade → secured cluster upgrade → additional procedures
• Check: All sections render correctly with proper hierarchy

Step 2: Verify roxctl CLI Upgrade Procedure

• Location: Included procedure module
• Verify: CLI upgrade steps are clear and complete
• Check: Platform-specific instructions (Linux, macOS) are accurate

Step 3: Verify Secured Cluster Upgrade Procedure

• Location: Included procedure module
• Verify: Secured cluster upgrade steps are sequential and correct
• Check: Prerequisites and post-upgrade verification steps are included

Step 4: Verify SCC Migration Content

• Location: Included procedure module
• Verify: Security Context Constraints migration steps are accurate
• Check: OpenShift-specific configuration is correct

Step 5: Verify Cross-Assembly Impact

• Open: Installing roxctl CLI
• Verify: Attribute references render correctly in CLI installation docs
• Check: Product names appear correctly, no placeholders visible

Verification Checklists

Structural Verification

• Assembly includes upgrade modules in logical workflow order
• New modules follow DITA naming conventions
• Module types align with content (PROCEDURE)
• Include statements use correct file paths

Content Verification

• roxctl CLI upgrade steps remain complete
• Secured cluster upgrade workflow is clear and accurate
• SCC migration procedure preserves technical details
• No upgrade content lost during reorganization
• Product names render correctly (no attribute placeholders)

DITA Compliance Verification

• CLI upgrade extracted into reusable procedure module
• Secured cluster upgrade extracted into focused module
• Each procedure module addresses single upgrade task
• Content enables reuse across assemblies
• Attribute references use correct Asciidoc syntax

Quick Visual Review Guide

Key elements to check in Netlify preview:

1. Upgrade workflow: Clear progression from CLI → secured clusters
2. Procedure formatting: Steps are numbered and sequential
3. Code blocks: Command examples render with proper syntax highlighting
4. Platform guidance: Linux and macOS instructions are distinguishable
5. Technical accuracy: Upgrade commands and configurations are correct
6. Cross-references: Links to related upgrade procedures work

[openshift-ci]

@agantony: all tests passed!

Full PR test history. Your PR dashboard.

Details

Instructions for interacting with me using PR comments are available here. If you have questions or suggestions related to my behavior, please file an issue against the kubernetes-sigs/prow repository. I understand the commands that are listed here.

[agantony]

/cherrypick rhacs-docs-4.11

[agantony]

/cherrypick rhacs-docs-4.10

[openshift-cherrypick-robot]

@agantony: new pull request created: #119104

Details

In response to this:

/cherrypick rhacs-docs-4.11

Instructions for interacting with me using PR comments are available here. If you have questions or suggestions related to my behavior, please file an issue against the kubernetes-sigs/prow repository.

[openshift-cherrypick-robot]

@agantony: new pull request created: #119105

Details

In response to this:

/cherrypick rhacs-docs-4.10

Instructions for interacting with me using PR comments are available here. If you have questions or suggestions related to my behavior, please file an issue against the kubernetes-sigs/prow repository.