Skip to content

Add runtime/service upgrade guide, de-emphasize Redis as one-off - #5711

Draft
catplat wants to merge 5 commits into
mainfrom
docs/upgrade-runtimes-deemphasize-redis
Draft

Add runtime/service upgrade guide, de-emphasize Redis as one-off#5711
catplat wants to merge 5 commits into
mainfrom
docs/upgrade-runtimes-deemphasize-redis

Conversation

@catplat

@catplat catplat commented Aug 14, 2026

Copy link
Copy Markdown
Collaborator

Independent of #5709 / #5710 — no merge-order dependency

This PR branches directly from main and doesn't touch anything the other two PRs change. It can merge before, after, or in parallel with them.

Summary

Adds "Upgrade to a maintained version of a runtime or service", a new tutorial covering the general upgrade workflow and both version-status classifications in use, ported from the equivalent Upsun Flex guide (devcenter-mintlify#648). Links to it from add-services/_index.md — the only in-repo pointer to this new page besides redis.md.

This page doesn't exist on main today, so this is a new page landing, not an edit to existing content.

De-emphasizing Redis

The previous draft of this page (never merged — it lived as an uncommitted/local-only version) framed Redis as the one-off exception to the Supported/Deprecated model, with codetabs literally titled "Redis" and "All other runtimes and services." This PR reframes it as a phased migration:

  • Codetabs renamed to Active/Sunset/Decommissioned and Supported/Deprecated/Retired — named after the classification system, not the service that happens to use it
  • The note now reads "Some runtimes and services (for example, Redis)... Others currently use... until they migrate... This migration happens in phases..."
  • Added Retired and Decommissioned* rows to the legacy classification table, matching the upstream Mintlify source's added nuance about upstream-only status with no enforcement
  • Renamed the "Version statuses" heading to "Image statuses" for consistency with its own body copy (was previously a mismatch — link text said "Image statuses" while pointing at a heading titled "Version statuses")

Scope note

Intentionally did not port Mintlify's "Available runtimes"/"Available services" static link lists — that page's own code comments flag those as a stopgap (TODO: replace with a dynamically generated list from the meta API). This repo already gets the same effect via the existing [Languages](/languages/_index.md) / [Add services](/add-services/_index.md) links, without the duplicate-list maintenance burden.

Verification

Local Hugo build confirms the new page renders correctly, both codetabs display as expected, and all cross-references (including the two links from redis.md to #image-statuses) resolve. Content-page rendering succeeded even though the CSS asset pipeline failed in the verification worktree (missing node_modules/PostCSS, unrelated to this content — confirmed by inspecting the rendered HTML before that failure).

Test plan

  • Confirm the new page reads sensibly on its own (not just as a diff)
  • Confirm redis.md's links to #image-statuses still resolve once this merges

Adds "Upgrade to a maintained version of a runtime or service", a new
tutorial covering the general upgrade workflow and both version-status
classifications in use, ported from the equivalent Upsun Flex guide
(devcenter-mintlify#648). Links to it from add-services/_index.md,
the only in-repo pointer to this new page besides redis.md.

Frames Redis as one example of a phased migration rather than a
permanent one-off exception: the codetabs are named after the
classification system (Active/Sunset/Decommissioned vs. Supported/
Deprecated/Retired) instead of by service, and the note explains that
other runtimes and services migrate to the new classification over
time. Also adds the Retired/Decommissioned* rows to the legacy
classification table, and renames the "Version statuses" heading to
"Image statuses" for consistency with its own body copy.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pull request overview

This PR adds a new tutorial page that explains how to upgrade runtimes/services to maintained images and clarifies the two image-status classification systems used across the docs. It also links to this new tutorial from the “Add services” index to make the guidance discoverable from service documentation entry points.

Changes:

  • Added a new tutorial: “Upgrade to a maintained version of a runtime or service,” including guidance on image status classifications (Active/Sunset/Decommissioned vs Supported/Deprecated/Retired).
  • Documented upgrade workflows for runtimes and services, including in-place upgrades and manual data-migration steps.
  • Linked the new tutorial from add-services/_index.md for easy discovery.

Reviewed changes

Copilot reviewed 2 out of 2 changed files in this pull request and generated 3 comments.

File Description
sites/platform/src/learn/tutorials/upgrade-runtimes-services.md New tutorial page describing image statuses and upgrade workflows for runtimes/services.
sites/platform/src/add-services/_index.md Adds a link pointing readers to the new upgrade tutorial for step-by-step guidance.
Suppressed comments (1)

sites/platform/src/learn/tutorials/upgrade-runtimes-services.md:154

  • As written, this tells readers to push before creating the non-production branch. Reorder this step so the branch is created first (if needed) and then pushed.
2. Push to a non-production branch:

   ```bash
   git add {{< vendor/configfile "services" >}}
   git commit -m "Update service version"

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

Comment thread sites/platform/src/learn/tutorials/upgrade-runtimes-services.md Outdated
Comment thread sites/platform/src/learn/tutorials/upgrade-runtimes-services.md Outdated
1. **Use preview environments**. Leverage preview (non-production environments) to perform the upgrade, then merge the upgrade into production (promotion). This will give you an opportunity to test inherited production data in a safe, isolated environment first.
1. **Upgrade progressively**. For one reason or another, you may be more than a single version behind the upgrade you are trying to perform. To avoid data loss issues caused by large differences in versions, [upgrade one version at a time](https://www.rabbitmq.com/upgrade.html#rabbitmq-version-upgradability).

For step-by-step instructions, including how to migrate data when a service doesn't support an in-place upgrade, see [Upgrade a runtime or service](/learn/tutorials/upgrade-runtimes-services.md).
Co-authored-by: catplat <215163593+catplat@users.noreply.github.com>
catplat and others added 2 commits August 14, 2026 18:43
Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>
Aligns the "Upgrade a service" branch-push step with the "Upgrade a
runtime" step: one sentence covering both cases, and a single code
block with branch creation before the git commands, rather than a
separate follow-up block.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Projects

None yet

Development

Successfully merging this pull request may close these issues.

5 participants