mcpField
R
rhdh-backstage-upgrade

rhdh-backstage-upgrade

github.com/redhat-developerDevelopment1948 installsUpdated 1d ago
Repository

About rhdh-backstage-upgrade

A skill for upgrading Backstage dependencies in RHDH repositories, aimed at developers maintaining RHDH projects. It identifies current and target versions, then guides dependency updates, migrations, breaking-change fixes, and validation while respecting the target RHDH compatibility level.

Key features

  1. 01Discover current Backstage versions
  2. 02Choose targets from RHDH compatibility
  3. 03Bump dependencies and inspect resolutions
  4. 04Migrate packages and address breaking changes
  5. 05Run repository-defined validation commands

Use cases

  1. 01Upgrade Backstage dependencies to a target version
  2. 02Check alignment with an RHDH release
  3. 03Fix API changes introduced by an upgrade
  4. 04Validate builds and tests after upgrading

Install

Copy the command and run it in a terminal.

$npx skills add https://github.com/redhat-developer/rhdh-skills --skill rhdh-backstage-upgrade

After installing, type/rhdh-backstage-upgradein Claude Code to confirm it loaded.

Bundled files

References and scripts installed along with SKILL.md.

agents/
openai.yaml
references/
bump-deps.md
determine-target.md
discover-versions.md
fix-breaking-changes.md
migrate-packages.md
verify-upgrade.md
workflows/
upgrade-backstage.md

Details

From the project README

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

  1. Read package.json and backstage.json before changing any dependency.
  2. 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.
  3. Report current versions and the proposed target before running a bump.

Route by outcome

OutcomeLoad and follow
Run the whole upgradeworkflows/upgrade-backstage.md
Find the current versions and any misalignmentreferences/discover-versions.md
Choose the target releasereferences/determine-target.md
Bump the dependency setreferences/bump-deps.md
Move imports off renamed or relocated packagesreferences/migrate-packages.md
Work through the breaking changes between releasesreferences/fix-breaking-changes.md
Verify the upgradereferences/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.

Comments

Markdown supported