Skip to content

docs: document the Roll Forward patch action - #670

Merged
AbhishekDoshi26 merged 9 commits into
mainfrom
docs/document-roll-forward
Sep 17, 2026
Merged

AbhishekDoshi26 merged 9 commits into
mainfrom
docs/document-roll-forward

Conversation

@AbhishekDoshi26

@AbhishekDoshi26 AbhishekDoshi26 commented Sep 16, 2026

Copy link
Copy Markdown
Member

Why

The console has a Roll Forward action on rolled back patches, but
rollback.mdx never mentioned it. The docs read as though rolling back were a
one-way door, which is the opposite of the point we make elsewhere when we tell
users to roll back rather than delete a release.

What changed

All in rollback.mdx:

  • New "Roll a patch forward" section: where the action lives in the console, that it only appears on a patch that is currently rolled back, and what happens on device (the patch stops being reported as rolled back, so devices pick it up on their next patch check).
  • A note that devices downgraded by the rollback have to download the patch again and that it counts against monthly patch installs, mirroring the caveat already documented for rollback itself.
  • A "When rolling forward is unavailable" subsection: releases built on a Flutter version without rollback support offer Deactivate instead, which behaves differently on device (already-installed devices keep the patch) and is undone by moving the patch back to the stable track rather than by rolling forward.
  • One line in the intro pointing out that a rollback is reversible.
  • A console screenshot of the Roll Forward menu item on a rolled back patch (src/assets/roll_forward_button.png), matching the existing screenshot for the Rollback action.

Verification

prettier, cspell, and vale clean; astro build passes with "All internal
links are valid", including the new #roll-a-patch-forward anchor.

The console exposes a "Roll Forward" action on rolled back patches, but
rollback.mdx never mentioned it, so the docs read as though a rollback were
one-way.

- Add a "Roll a patch forward" section covering where the action lives, that
  it only appears on a currently rolled back patch, and what happens on device
  when a patch is rolled forward.
- Note that re-downloading the patch counts against monthly patch installs,
  matching the existing caveat for rollback.
- Explain that releases on Flutter versions without rollback support get
  Deactivate instead, how that differs on device, and that it is undone by
  moving the patch back to the stable track rather than by rolling forward.
- Mention in the intro that a rollback is reversible.
The updater downloads in the background and applies on the next restart, per
"When do updates happen?"; say that rather than "install it the next time the
app starts". Also drop the claim that a never-rolled-back patch shows
"Rollback", which is only true on releases that support rollback at all.
@AbhishekDoshi26

Copy link
Copy Markdown
Member Author

Self-review

Re-read this against the console source and the rest of the docs. Two wording fixes pushed in 996608e, plus one correction I had already made before opening the PR.

Fixed: update timing did not match our own FAQ

I wrote that devices "pick it up on their next patch check and install it the next time the app starts." Per "When do updates happen?", the updater checks on startup, downloads in the background during that session, and applies the patch on the next restart. Now worded as download on the next check, apply on the next restart, so the two pages agree.

Fixed: overstated when Rollback appears

"A patch that has never been rolled back shows Rollback instead" is only true on releases that support rollback at all. On releases that do not, the menu offers Deactivate and neither Rollback nor Roll Forward appears. Reworded to say the same menu offers Rollback on a patch that is not rolled back, which is true in the context where Roll Forward is relevant.

Corrected before opening: deactivation is reversible

My first draft said deactivation could not be undone and that you would have to publish a new patch. That is wrong. Deactivate promotes the patch to a deactivated channel, and Change Track is always available, so moving it back to stable reverses it. The section says that now and gives the patches set-track equivalent. This is the claim I would most like a second opinion on, since I am describing the mechanism rather than repeating existing copy.

Verified

  • Roll Forward appears only when the patch is currently rolled back, and only on releases that support rollback.
  • Rolling forward clears the rolled-back flag and the cached patch-check response, so the patch becomes servable again, matching "becomes the active patch for its track."
  • The patch-install caveat follows from the billing page's own definition (a successful update applied on a device) and mirrors the caveat already documented for rollback itself.

Still open for you

  • The page's existing note that rollback "requires a minimum Flutter version of 3.27.4" does not match how the check actually works. Support is decided by a revision blocklist with no version floor, because the feature was backported across fork branches, so a strict reading of that sentence is not the real gate. I left it alone as out of scope. Happy to reword it here or separately.
  • No screenshot for the Roll Forward menu item, while the rollback section has one for its button. Point me at an image and I will add it.

prettier, cspell, vale clean; astro build reports all internal links valid, including the new #roll-a-patch-forward anchor.

@AbhishekDoshi26
AbhishekDoshi26 force-pushed the docs/document-roll-forward branch from ef28dbc to 09aab36 Compare September 16, 2026 11:48

@dawn-ducky dawn-ducky left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Changes and questions for clarity

Comment thread src/content/docs/code-push/rollback.mdx Outdated
Comment thread src/content/docs/code-push/rollback.mdx
Comment thread src/content/docs/code-push/rollback.mdx Outdated
- Mention roll forward in the page description
- Drop wording implying rollbacks count against patch installs
- State the Flutter versions that lack rollback (3.22.2 and earlier) and
  correct the minimum version note to 3.22.3
… Forward

Rollback support is not cleanly bounded by a Flutter version (early
3.22.3 builds predate it), so restore the original minimum version note
and remove the section describing unsupported releases.
@AbhishekDoshi26
AbhishekDoshi26 merged commit 221609f into main Sep 17, 2026
3 checks passed
@AbhishekDoshi26
AbhishekDoshi26 deleted the docs/document-roll-forward branch September 17, 2026 08:23
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants