Skip to content

[opencode] docs: add vanilla-first policy to backstage-upgrade skill #103

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
johnnyhuy merged 1 commit into from
Oct 3, 2026
Merged

[opencode] docs: add vanilla-first policy to backstage-upgrade skill #103

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
21 changes: 16 additions & 5 deletions .claude/skills/backstage-upgrade/SKILL.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -27,6 +27,15 @@ Use this skill when upgrading a Backstage monorepo to a newer version.
- Backstage Yarn plugin installed (makes version management easier)
- Clean git state (commit or stash changes before upgrading)

## Vanilla-first policy

This repo should stay as close to the vanilla `create-app` template as possible. Every upgrade is a chance to remove drift, not add it.

- Apply the create-app template changes from the upgrade-helper diff by default. Skip one only when a deliberate customisation already lives in that file (custom theming, `@internal/*` plugins, RBAC policy, Plausible), and say so in the commit or PR body.
- When an upgrade breaks, use the fix vanilla adopters would need. A one-line entry in existing config (e.g. a `resolutions` workaround for an upstream packaging bug) beats vendored files, version pins, extra Docker layers, or forked patches.
- Do not add permanent deviations to structural files (`Dockerfile`, `tsconfig.json`, `app-config.yaml`, workspace manifests) beyond what the repo already customises for a documented reason.
- If a local workaround is unavoidable, keep it minimal, reference the upstream issue, and delete it once upstream is fixed.

## Upgrade Workflow

### Step 1: Check current state
Expand Down Expand Up @@ -70,18 +79,20 @@ yarn backstage-cli versions:bump --pattern '@{backstage,roadiehq}/*'

This updates `backstage.json` and migrates package.json deps to use `backstage:^` if the yarn plugin is installed.

### Step 4: Pull in template changes
### Step 4: Reconcile with the vanilla template

The `create-app` template changes are NOT auto-applied. Check manually:
The `create-app` template changes are NOT auto-applied. Fetch the upgrade-helper diff for the exact jump and work through it file by file:

```bash
# Use upgrade helper for diff between versions
open https://backstage.github.io/upgrade-helper/?from=<old>&to=<new>&yarnPlugin=1

# View changelog
yarn dlx @backstage/create-app@latest --version 2>/dev/null

# Use upgrade helper for diff between versions
open https://backstage.github.io/upgrade-helper/?yarnPlugin=0
```

Apply the template version of every changed file by default. Keep local edits only where this repo deliberately deviates (theming, `@internal/*` plugins, RBAC, Plausible), re-applied on top of the template's file rather than skipping the update. List anything kept back in the commit or PR body.

Key files that often change in templates:
- `packages/backend/src/index.ts`
- `packages/app/src/App.tsx`
Expand Down
Loading