RHDH Backstage Upgrade
Own version numbers. Which @backstage/* release a checkout sits on, which
release it should move to, and everything that breaks in between.
Start here
- Read
package.json and backstage.json before changing any dependency.
- Establish the target RHDH version. Prefer an explicit user or repository
value; otherwise invoke
/rhdh-context for the checked-in compatibility
matrix. If it is unavailable, ask the user for the target RHDH and Backstage
versions rather than guessing.
- Report current versions and the proposed target before running a bump.
Route by outcome
| Outcome |
Load and follow |
| Run the whole upgrade |
workflows/upgrade-backstage.md |
| Find the current versions and any misalignment |
references/discover-versions.md |
| Choose the target release |
references/determine-target.md |
| Bump the dependency set |
references/bump-deps.md |
| Move imports off renamed or relocated packages |
references/migrate-packages.md |
| Work through the breaking changes between releases |
references/fix-breaking-changes.md |
| Verify the upgrade |
references/verify-upgrade.md |
Boundaries
- This skill owns version numbers. It does not change what a plugin's
extensions are or how they attach.
/rhdh-plugin-nfs-migration owns extension shape: converting a legacy
frontend plugin's extensions into New Frontend System Blueprints. The two
skills meet whenever an upgrade is a prerequisite for a migration, or a
migration surfaces an outdated dependency set. Bump the versions here; change
the extensions there./backstage-api-changes owns the NFS API deltas between the early alpha
and the current GA surface. Invoke it by name when an upgrade breaks NFS code
— a removed NavItemBlueprint, a config.schema block that must become
configSchema, or a renamed blueprint param./rhdh-context owns the RHDH-to-Backstage compatibility matrix./rhdh-plugin-authoring owns non-mechanical source changes the upgrade
exposes./rhdh-pr-create owns staging, commits, and pull requests.
Invoke a named skill and describe the handoff in the conversation. Never open
another skill's files.
Invariants
- Never upgrade past the Backstage version the target RHDH release ships. The
resolved compatibility answer wins over the newest available release.
- Use the checkout's
versions:bump script when it wraps
backstage-cli versions:bump; otherwise use the CLI directly. Review the
resulting package.json and lockfile diff before continuing.
- Inventory every resolution and override before the bump. Compare its package
manager dependency paths before and after, then record the provenance and
evidence for keeping, updating, or removing it.
- Read the changelog for every release between the old and new version, then
search the source for each affected API. Do not assume a range is
breaking-change free.
- If current and target match, say "already on target" and stop.
- Run every validation command the checkout defines for build, test, lint,
formatting, and monorepo consistency before reporting the upgrade complete.
- Do not stage, commit, push, or open a pull request here.
Completion
Report the versions found, the target chosen and where the answer came from,
the commands run, the breaking changes fixed and the files they touched, every
resolution and override with its provenance, before/after graph evidence and
keep/update/remove reason, any range-style change, generated files, the
verification results, and any dependency left misaligned with a reason.
1---2name: rhdh-backstage-upgrade3description: Moves the @backstage/* dependency versions of a Backstage plugin, workspace, app, or the redhat-developer/rhdh monorepo forward to a chosen release, staying within what a Red Hat Developer Hub version ships: read backstage.json and package.json, pick the target from the RHDH compatibility matrix or an explicit version, run versions:bump and versions:migrate, preserve the repository's dependency range style, audit stale resolutions, work through release changelogs, and re-verify the repository. Use for "upgrade @backstage dependencies", "bump Backstage in rhdh", "versions:bump", "which Backstage version does RHDH 1.8 ship", moved package namespaces, or dependencies that are too old for the API they need.4---56# RHDH Backstage Upgrade78Own **version numbers**. Which `@backstage/*` release a checkout sits on, which9release it should move to, and everything that breaks in between.1011## Start here12131. Read `package.json` and `backstage.json` before changing any dependency.142. Establish the target RHDH version. Prefer an explicit user or repository15 value; otherwise invoke `/rhdh-context` for the checked-in compatibility16 matrix. If it is unavailable, ask the user for the target RHDH and Backstage17 versions rather than guessing.183. Report current versions and the proposed target before running a bump.1920## Route by outcome2122| Outcome | Load and follow |23|---|---|24| Run the whole upgrade | `workflows/upgrade-backstage.md` |25| Find the current versions and any misalignment | `references/discover-versions.md` |26| Choose the target release | `references/determine-target.md` |27| Bump the dependency set | `references/bump-deps.md` |28| Move imports off renamed or relocated packages | `references/migrate-packages.md` |29| Work through the breaking changes between releases | `references/fix-breaking-changes.md` |30| Verify the upgrade | `references/verify-upgrade.md` |3132## Boundaries3334- This skill owns **version numbers**. It does not change what a plugin's35 extensions are or how they attach.36- `/rhdh-plugin-nfs-migration` owns **extension shape**: converting a legacy37 frontend plugin's extensions into New Frontend System Blueprints. The two38 skills meet whenever an upgrade is a prerequisite for a migration, or a39 migration surfaces an outdated dependency set. Bump the versions here; change40 the extensions there.41- `/backstage-api-changes` owns the NFS API deltas between the early alpha42 and the current GA surface. Invoke it by name when an upgrade breaks NFS code43 — a removed `NavItemBlueprint`, a `config.schema` block that must become44 `configSchema`, or a renamed blueprint param.45- `/rhdh-context` owns the RHDH-to-Backstage compatibility matrix.46- `/rhdh-plugin-authoring` owns non-mechanical source changes the upgrade47 exposes.48- `/rhdh-pr-create` owns staging, commits, and pull requests.4950Invoke a named skill and describe the handoff in the conversation. Never open51another skill's files.5253## Invariants5455- Never upgrade past the Backstage version the target RHDH release ships. The56 resolved compatibility answer wins over the newest available release.57- Use the checkout's `versions:bump` script when it wraps58 `backstage-cli versions:bump`; otherwise use the CLI directly. Review the59 resulting `package.json` and lockfile diff before continuing.60- Inventory every resolution and override before the bump. Compare its package61 manager dependency paths before and after, then record the provenance and62 evidence for keeping, updating, or removing it.63- Read the changelog for every release between the old and new version, then64 search the source for each affected API. Do not assume a range is65 breaking-change free.66- If current and target match, say "already on target" and stop.67- Run every validation command the checkout defines for build, test, lint,68 formatting, and monorepo consistency before reporting the upgrade complete.69- Do not stage, commit, push, or open a pull request here.7071## Completion7273Report the versions found, the target chosen and where the answer came from,74the commands run, the breaking changes fixed and the files they touched, every75resolution and override with its provenance, before/after graph evidence and76keep/update/remove reason, any range-style change, generated files, the77verification results, and any dependency left misaligned with a reason.
redhat-developer