General availability tasks

These directions walk you through preparing for the release and tasks for GA day. Ideally this is done by a strategist/architect or a lead with a big-picture view of the doc, but as long as a teammate has rights, they can go through these procedures.

Prerequisites

You must have the following prerequisites to publish live:

  • Minimum KCS1 access to the Customer Portal and Pantheon
  • Connection to the VPN
  • Logged in to the Pantheon UI
  • Feature doc and release work is completed for GA

Tasks to complete early staging

In addition to the release work, the lead or the strategists must follow up on general tasks each release before GA. Best practice: Open a story on the Documentation component to track along side the dev stories. Attach issues that can be shared if needed for the following tasks (you can combine similar tasks in one issue):

  1. Remove old What’s new entries so that the team can start over for the new release.
  2. Remove deprecation and removal items that are older than staged-N minus two (the squads help with this via the cross-squad issue).
  3. Clean the Errata release notes to only have the intro (both MCE and ACM).
  4. Update link versions for OCP. (Currently we use the earliest of N-2, unless the feature is built on a later OCP. See PM for guidance. If this changes, we need to change the note we added about this.)
  5. Update any other versions, such as channel, RHEL, etc…. Get guidance from a tech lead on this.
  6. Change support matrix links.
  7. If something went EOL, ensure the latest doc reflects those changes. See Deprecating and removing for that guidance.
  8. Work with console focal and engineers to ensure links in the console have not changed. You will need to know the deadline for code changes from the UI team.

Preparing for Pencils Down

At some point the team agrees to a Pencils Down date, which may move depending on the product release. Close to that date, start preparing.

  1. Ensure the build is regularly green. Ask writers fix any errors for their books a few days before GA and work to keep the build green closer to the agreed upon Pencils Down day.
  2. Ask the team to work on reconciling the changes and merging active PRs to the stage branch. Since this depends on reviews and such, the PR list may not be clear in time, but no PRs for stage is the goal for Pencils Down.
  3. Declare Pencils Down on the date/time so that the team pauses any pushing to stage.
  4. Build stage. Check for green. Fix any errors.

Creating production branch from stage

Now that stage branch is finalized and green, you can create the production branch from the stage branch. See Branch Strategy for important information about how and why we use these branches.

  1. Create the new _prod branch from the _stage branch.
  2. Protect the branch to keep anyone from bypassing rules in the production branch. Two users are needed to push stage into to prod: The creator and the reviewer. Go to Settings > Branches. (Because GitHub changes the UI at times, if this is not the workflow, you can simply Google something like “how to protect my branch in GitHub” for the process.)
  3. Select Add rule in the Branch protection rules section.
  4. Add the branch name to the Branch name pattern. Example: 2x_prod.
  5. Select Require a pull request before merging.
  6. Ensure that Require approvals is selected.
  7. Select Include administrators to prevent admins from bypassing this rule. Admins can bypass in stage IF needed, but not prod.
  8. Select Create to apply the rule.
  9. Run a build wit the prod branch in the command: ./acm_sync_asciidoc.sh 2.x 2.x_prod
  10. Ensure the build is clean.
  11. Stop any builds until GA day and after because prod and stage are in the same directory. You can return to building stage after you publish.

Publishing doc and splash page

Ideally the architect or strategist is doing this but can be done by the lead, with overall big-picture in mind. See support from the DE/PM about arranging this when needed.

  1. Log in to Pantheon.
  2. See the Publish a GA version section of Refreshing builds and complete the procedure.
  3. Click Splash Pages in the navigation to view the splash pages. If you are not logged in to Pantheon, you will not see this item in the navigation.
  4. Find the entry for Red Hat Advanced Cluster Management for Kubernetes. The entry should show the version of the product that you are pushing, with an unpublished label.
  5. Click the name of the product to open the splash page.
  6. Add the categories for the documentation and drag the books into the correct categories, if necessary.
  7. When you are ready to publish it, expand Update/view product status.
  8. Change the Product status from Unpublished to Published.
  9. Click Save to save the changes.

This was something that we had to update but is now handled through an issue with more process attached.

  1. Clone CPPX-948 and update the version numbers. This example was used for version 2.12.
  2. Request an update to the Support Matrix link on the product page to the new support matrix.
  3. Submit the issue. It is usually a very fast turnaround.

Additional required tasks

  1. Publish the draft(s) for the Support Matrix. There should be an issue for the release that tracked this work. See the strategist or lead. Currently there is a matrix for ACM and MCE.
  2. Edit Comet. (?)
  3. Add the Support matrix to the Lifecycle page.
  4. Double check that links to the Support matrix work after you publish.
  5. Reach out at the earliest convenience to get the Jira template changed with the following note (or something similar) to rh-issues@redhat.com:
When you create the Jira for the ACM Doc team, you choose the **Documentation** component to see the **Doc template** for requested Customer Portal changes. All issue types would display this template because it is controlled by the component, `Documentation`. Please update the current link with the latest published doc that just went live: `<insert link to landing page for most recent doc>`