keeping-backstage-updated.md

The challenge of keeping Backstage up-to-date, is that it is meant as a template for a developer portal, supported by a platform of standardized plugins. Although it is fairly easy to bump the dependencies for the plugins, one also have to update the template, which becomes more and more difficult as changes are made locally. To solve for this, the official documentation recommends that upgrades are made in the following order:

1. Bump dependencies using yarn backstage-cli versions:bump
2. Read the @backstage/create-app changelog and/or use the Backstage upgrade helper to modify the code generated by the initial template.

Our approach

An alternative approach, which is described in this document, is to maintain a separate git branch within the repository, named backstage-latest, for the output generated by @backstage/create-app, and continuously merge those changes into the main branch. This gives git the possibility to perform a three-way merge which helps resolve merge conflicts.

Or, conceptually, we may think of our main branch to be a fork of the output from @backstage/create-app, and we use merges to apply upstream changes.

(Image created by mermaid)

Updating the backstage-latest branch

The backstage-latest branch is maintained by a github workflow

name: Update backstage-latest branch

on:
  workflow_dispatch:

jobs:
  update-backstage-latest:
    runs-on: ubuntu-latest
    steps:
    - uses: actions/checkout@v2
      with:
        ref: 'backstage-latest'
    - uses: actions/setup-node@v3
      with:
        node-version: 16
    - name: Update backstage-latest branch
      run: |
        git config user.name github-actions
        git config user.email github-actions@github.com
        VERSION=$(npm show @backstage/create-app version)
        git clean -fd && git rm -rf .
        echo backstage | npx --yes @backstage/create-app@$VERSION --path . --skip-install
        git add .
        git commit -m "Bump backstage using @backstage/create-app@$VERSION" || true
        git push

Merging the backstage-latest branch into main

1. Create a temporary branch from main and merge backstage-latest

   # Make sure that we are up-to-date with the latest branches on GitHub
   git fetch
   
   # Create a temporary branch called `bump-backstage` where we will be performing the merge, also allowing us
   # to test the results against our development environment. 
   git switch -C bump-backstage origin/main
   
   # Merge the `backstage-latest` branch *into* our temporary branch.
   git merge origin/backstage-latest

2. Resolve conflicts using three-way merge. WebStorm has an excellent merge-tool for this purpose in Git > Resolve Conflicts.
3. Update yarn.lock and push the branch

   yarn install
   # Fix any mismatches in versions
   yarn backstage-cli versions:check --fix
   git commit -m 'Merge backstage-latest'
   git push -u

4. Test your branch. Once satisfied, merge bump-backstage manually (not using GitHub) using the following commands, because we want to keep the merge commit intact.

   git checkout main
   git merge --ff-only origin/bump-backstage
   git push