Patch Several Releases
A bug found today is often in more than the latest release. Users update from the stores at their own pace, so last week’s release and the one before it may still be on many devices. To reach all of them, patch each release that has the bug.
Each patch is for one release on one platform: a fix in three releases is three patches per platform. This guide shows how to build them from the right code, run them side by side in CI so three take about as long as one, and hand the routine part to an AI agent.
Choose the releases
Section titled “Choose the releases”Patch the releases your users still run. The Shorebird Console shows each release’s active devices, and so does an AI app connected to Shorebird (“Which old versions are still out there?”). List the releases on a platform with:
A release with few users left may not be worth a patch: those users get the fix when they update from the store.
Build each patch from its release’s code
Section titled “Build each patch from its release’s code”A patch replaces all of the release’s Dart code with the code you build it from, so it must include the fixes from that release’s earlier patches. Build each patch from the release’s branch, which holds those fixes, with the new fix added. For one release:
Everything on the branch ships, so first check it has no commits from a patch you rolled back or rejected. Then the new patch adds only the fix. That keeps it small and, on iOS, keeps most of its code running natively; see Link percentage and slow patches. This needs a branch for each release; the Development Workflow guide sets one up. If a release only has a tag, create its branch from the tag and cherry-pick the fixes from any patches the release already has.
You can build a patch for an older release from newer code, such as main, and
shorebird patch builds it with the release’s Flutter version. That patch
carries every Dart change made since the release, not only the fix, so test it
as you would a new release. If native code or assets changed since the release,
shorebird patch warns and asks whether to continue, or stops where it can’t
ask, as in CI. On iOS, the more the code has changed, the more of it runs in the
interpreter, and shorebird patch refuses a patch that
links below its minimum.
Each patch also needs the build flags its release used, such as --dart-define
and --flavor. If they differ between releases, pass each release’s own; see
A patch uses the build flags of its release.
Put the fix on each release’s branch
Section titled “Put the fix on each release’s branch”To patch several releases in CI, first cherry-pick the fix onto each release’s branch and push. Leave out any branch you’ve already done:
The loop stops at the first branch where this fails. If the fix doesn’t apply
cleanly, resolve it there and push. If the branch already has the fix, run
git cherry-pick --skip. Then run the loop for the remaining branches. If a
branch is protected, get the fix onto it through your usual pull request.
Patch the releases in parallel in CI
Section titled “Patch the releases in parallel in CI”A patch takes about as long to build as a release. To patch several releases at
once, run one CI job per release. This GitHub Actions workflow takes a list of
releases and builds an Android patch from each release’s branch in its own job,
onto the staging track. It only reads your repository:
Commit this file to your default branch first: GitHub only offers a manual run for a workflow that is on the default branch. Then run it from the Actions tab, or from a terminal with the GitHub CLI:
Each entry’s ref is that release’s own branch. If a release used its own build
flags, add them to its entry as args, such as "args": "--flavor prod". The
patch action parses args as shell words, so treat this field like code, and
don’t put secret values in it: anyone who can read the run can see them. If two
entries share a version, as flavors can, add a label to tell them apart in the
run’s summary. To single-quote a value containing $ or spaces, keep the list
in a file and pass it with -f releases="$(cat releases.json)". If an older
branch needs a different Java version, add a java field and use it for
java-version.
For iOS, add a patch-ios job on a macOS runner, with this job’s strategy and
its branch check, checkout and patch number steps, with the number’s label
changed to iOS. Take the Shorebird, Xcode and signing setup from the iOS job in
the Development Workflow
guide, and use this patch step:
Each patch must build with its release’s Xcode, and a release’s iOS version can
differ from its Android one. If yours do, add fields such as ios_version,
xcode and runner to each entry and use them in this job.
Each job uses its own runner, so patching four releases takes about the time of one, and four times the runner minutes. If a job fails, fix the cause and run the workflow again for that release alone.
Test and promote each patch
Section titled “Test and promote each patch”Each release gets its own patch on each platform, with its own patch number, which the workflow run’s summary lists. Preview each one on the staging track:
Then promote each patch, on every platform you patched, from the console or the command line:
If a release uses a flavor, add --flavor to these commands too. If testing
rejects a patch, revert the fix on that release’s branch, or its next patch will
ship the fix again. See Staging Patches
for more on the staging track.
Let an AI agent run it
Section titled “Let an AI agent run it”Choosing the releases, finding each one’s branch, checking that the fix applies
and starting the workflow is routine work an AI coding agent can do. Save this
as .claude/skills/patch-releases/SKILL.md in your repository for
Claude Code, or paste the
part after the header into any agent as a prompt. Edit the first step to say how
your team names release branches.
The agent needs the GitHub CLI signed in, and Shorebird signed in or a
SHOREBIRD_TOKEN to list releases. To let it answer which releases have the
most users, also connect it to Shorebird’s MCP server.