docs: document Shorebird with long-running Android background processes (shorebirdtech/shorebird#2396)

[AzazelSensei]

Status

READY

Description

I added a FAQ entry and a troubleshooting note for Android apps that keep a foreground service running. Swiping the app from Recents does not kill the process, so the patch never applies until a real process restart.

See shorebirdtech/shorebird#2396

[AbhishekDoshi26]

Thanks for picking this up, and for tying it to a concrete plugin rather than describing the problem in the abstract. This lands in the right two places, the FAQ heading matches the house "How do you ..." phrasing, and it's slotted next to When do updates happen?, which is where a reader would look. I checked the technical claims against the updater source and the maintainers' own statements and they hold up, which is not a given for a subtle topic like this.

I built the branch and ran the full lint suite. Two things block merge, one of which is not your fault, and there are a few structural points worth addressing before this goes in.

Blocking

1. prettier fails, which is what is making the build check red

Two lines in faq.mdx are wrapped a column short:

565:    stop the foreground service and then swipe the app away, or wait until the
566:    OS kills the process.
568: Recreating the Flutter engine without killing the process is not a supported
569: way to apply a patch.

Run npm run format and commit the result. That is the whole fix, nothing else in the repo is touched.

2. style-check is red, but not because of this PR

Ignore it. Vale 3.22.0 against your branch reports exactly one error, in flutter-concepts/how-to-install-flutter.mdx:342, a file you did not touch. It is a main branch breakage caused by Vale shipping a new release, and #678 fixes it. Once that merges, re-running this job will go green with no change from you.

Worth fixing before merge

3. Step 2 is developer instructions, not user instructions

This is the main substantive point, and it's in the inline comment on line 564.

Short version: package:shorebird_code_push exposes UpdateStatus.restartRequired and readNextPatch(), which exist for exactly this case. The FAQ currently spends step 1 on the package and then falls back to "Settings, Apps, Force stop" for step 2. Force stop is a fine way for you to verify behavior, but it is not something an app can ask its users to do, and this FAQ is aimed at shipping apps.

4. It overlaps with the entry 12 lines above it

When do updates happen? (line 533) already says updates "will be applied the next time the app is restarted" and already links the same package and the same Update Strategies page. Your entry is more precise, which is good, but it means a reader who hits the earlier entry first gets the vaguer answer and may never scroll to yours.

Consider sharpening the earlier entry's "the next time the app is restarted" to say process restart, so the two agree, and let your entry focus on what is specific to background processes. Either that or a short pointer from the earlier entry down to yours.

5. The troubleshooting bullet is phrased as a symptom, its siblings are causes

Detail in the inline comment on line 101.

Verified, no action needed

I want to call these out because they are the parts that are easy to get wrong:

• "Recreating the Flutter engine without killing the process is not a supported way to apply a patch" is correct, and matches eseidel's own reasoning in shorebirdtech/shorebird#2350: "The reason why we don't offer 'hot restart' of sorts is that we can't know if plugins will manage the restart correctly." Note that the reporter there confirmed engine recreation does work on Android in practice, so "not supported" is exactly the right framing, rather than "does not work".
• "not when an Activity is recreated" is right. An Activity recreation reuses the engine, so no patch is picked up.
• "Default automatic updates only run on process start" matches the Update Strategies page.
• The cross-link anchor resolves. I built the site and confirmed id="how-do-you-use-shorebird-with-a-long-running-android-background-process" is emitted, and the internal link validator passes on all pages.
• The link style [package:shorebird_code_push](...) without backticks matches the adjacent FAQ entry at line 541. update-strategies.mdx uses backticks, so the repo is inconsistent here, and matching your neighbour is the right call.
• cspell passes, and the build succeeds with 74 pages.

Nit

Line 564: the repo bolds UI navigation paths, for example **Account → API Keys** in this same file at line 73, and **Settings → Privacy & Security → For Developers** in how-to-install-flutter.mdx:195. Yours is unbolded.

[AzazelSensei]

Pushed the review notes: package API for the staged patch, Force stop as a testing note, process restart in When do updates happen, troubleshooting heading as a cause, and prettier wrap.

[AbhishekDoshi26]

Re-reviewed the update. You addressed all five points, and CI is now fully green (build, spell-check, style-check all pass, since #678 landed and cleared the unrelated Vale failure).

The rewritten step 2/3 split is exactly right, and sharpening When do updates happen? to say "the next time the process restarts" with a link down to the new entry fixes the contradiction properly rather than papering over it. Nice.

One thing left, and it is my mistake, not yours. The "how to tell" diagnostic I suggested in my last review is wrong on two counts. You implemented what I wrote, so this is me correcting my own bad advice. Details in the inline comment on line 107, corrected replacement included.

Everything else is good to merge once that is sorted.

Verified on this revision

• prettier, cspell, Vale 3.22.0, and the component-label linter all clean.
• astro build succeeds, 74 pages, internal link validator passes.
• Both new cross-links resolve: the same-page relative #how-do-you-use-... in faq.mdx and the absolute /code-push/faq/#how-do-you-use-... in troubleshooting.mdx. Using a relative anchor for the same-page link and an absolute one for the cross-page link is the correct call.
• The cause line now matches its siblings under Patch not showing up, and **Settings → Apps → Force stop** is bolded like the other UI paths in the repo.
• The UpdateStatus.restartRequired and readNextPatch() references match the current shorebird_code_push 2.0.7 API in shorebirdtech/updater.

[AbhishekDoshi26]

This is ready. You fixed the diagnostic, and you went one better by adding the **How to fix it** sub-heading as well, which I had not asked for but which makes this cause match the structure of the release-version cause directly above it. The troubleshooting entry now reads exactly like its siblings.

Thanks for working through three rounds on this, including one where the change I asked for was my own bad suggestion. The end result is better than what I originally proposed.

Verified on this revision

Ran the full suite against the merge of your branch with current main, which is what CI actually tests:

• Vale 3.22.0: 0 errors across 74 files.
• prettier, cspell, component-label linter: all clean.
• astro build: succeeds, 74 pages, internal link validator passes.
• Both cross-links resolve. id="how-do-you-use-shorebird-with-a-long-running-android-background-process" is emitted in the built FAQ page, and the troubleshooting page links to it.
• CI on the PR is green on build, spell-check and style-check.

Your branch is one commit behind main (#678 landed after you pushed), but since the checks run against the merge result and that is green, there is nothing for you to do about it.

Technical claims, re-checked against source

• UpdateStatus.restartRequired and readNextPatch() match the current shorebird_code_push 2.0.7 API in shorebirdtech/updater, including the semantics you describe: readNextPatch() returns the most recently downloaded patch and matches readCurrentPatch() when nothing new has been downloaded.
• adb shell pidof <your.package.name> is the right call over ps, and comparing the PID across the swipe is unambiguous.
• "Recreating the Flutter engine without killing the process is not a supported way to apply a patch" matches eseidel's reasoning in shorebirdtech/shorebird#2350.
• "not when an Activity is recreated" is correct, since an Activity recreation reuses the engine.
• Sharpening When do updates happen? to "the next time the process restarts" removes the contradiction at its source rather than leaving two answers on one page.

This resolves shorebirdtech/shorebird#2396. Approving.