docs(releasing): correct the runbook before it is used for 2.2.0 - #998
Merged
Conversation
Every claim checked against origin/release/2.2.0. Five were wrong, and the two that matter both concern the Android step -- the one part of a release that actually needs a human. - **The runbook said `android-deploy` uploads to the Play `internal` track.** It attempts to. Since 2.1.0 the bundle declares `android.permission.health.*` and the Publishing API rejects it with "You must let us know whether your app includes any health features" regardless of the declaration (#942). The step tolerates that one error, warns, and writes recovery steps into the run's step summary -- so a green job does not mean a build reached the track. A releaser following the old text believed it had. The recovery procedure is now on the page, including reading the console's review warnings, which is the only place Play reports them and how #959's minSdk regression sat unnoticed for eight days. "Promote the Android build" now says to check the summary first. - **`update-release-fingerprint.yml`, `deploy-site.yml` and `docs/site/` do not exist.** They went with the project website in #786, five days before this page was written -- so the section was false the day it was committed, and the checklist told the releaser to wait for a PR that nothing opens. Removed, and the Notes paragraph claiming those two workflows "exist only on `main`" replaced: neither exists anywhere, and the real difference is the reverse, `develop` carrying `ios-integration-attempt.yml` that `main` lacks. - **`fastlane/metadata/android/.../changelogs/` is in use again.** The page said to treat it as unused on the strength of a stale `12.txt`; `63.txt` now holds the 2.2.0 notes. The item now says to write the file, and that the pipeline still does not upload it. - The version-bump example moves from `2.0.2`/`+61` to `2.2.0`/`+63`. Refs #991
Contributor
There was a problem hiding this comment.
🟡 Changes recommended
The updated runbook text includes non-linking upstream issue references and an ungrammatical sentence in the Android-upload section that should be corrected before the doc is relied on for release steps.
Once you've addressed the issues Copilot identified, you can request another Copilot review.
Pull request overview
Updates the release runbook to accurately reflect current CI behavior for Android deployments (especially the Play Publishing API health-permission failure mode) and removes/adjusts outdated workflow and metadata guidance ahead of the 2.2.0 release.
Changes:
- Clarifies that
android-deploymay succeed while the Playinternalupload did not occur, and documents the manual recovery steps via the run step summary. - Updates the pre-release checklist to reflect current Play “what’s new” changelog file usage and manual store listing updates.
- Removes stale references to deleted website/fingerprint workflows and corrects the workflow-set differences between
mainanddevelop.
File summaries
| File | Description |
|---|---|
| docs/RELEASING.md | Corrects Android release instructions and removes/updates outdated workflow and metadata guidance. |
Review details
Suppressed comments (1)
docs/RELEASING.md:41
- This sentence is ungrammatical (“is asked no health question”). Reword to clearly state that the console upload does not prompt for the health declaration and succeeds.
bundle uploaded by hand through the console is asked no health question and goes through.
- Files reviewed: 1/1 changed files
- Comments generated: 1
- Review effort level: Lite
💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.
Copilot: `fastlane#22204` does not auto-link across repositories, so the tracking issues behind the Play upload defect were unreachable from the page that tells a releaser to work around it. Full URLs for both fastlane issues and the expo one.
Contributor
There was a problem hiding this comment.
🟢 Approval recommended
Documentation-only changes are consistent with the repository’s current workflows and reduce release risk without introducing code-path or operational changes.
Review details
- Files reviewed: 1/1 changed files
- Comments generated: 0 new
- Review effort level: Lite
simonoppowa
added a commit
that referenced
this pull request
Sep 1, 2026
* docs(releasing): correct the runbook before it is used for 2.2.0 Every claim checked against origin/release/2.2.0. Five were wrong, and the two that matter both concern the Android step -- the one part of a release that actually needs a human. - **The runbook said `android-deploy` uploads to the Play `internal` track.** It attempts to. Since 2.1.0 the bundle declares `android.permission.health.*` and the Publishing API rejects it with "You must let us know whether your app includes any health features" regardless of the declaration (#942). The step tolerates that one error, warns, and writes recovery steps into the run's step summary -- so a green job does not mean a build reached the track. A releaser following the old text believed it had. The recovery procedure is now on the page, including reading the console's review warnings, which is the only place Play reports them and how #959's minSdk regression sat unnoticed for eight days. "Promote the Android build" now says to check the summary first. - **`update-release-fingerprint.yml`, `deploy-site.yml` and `docs/site/` do not exist.** They went with the project website in #786, five days before this page was written -- so the section was false the day it was committed, and the checklist told the releaser to wait for a PR that nothing opens. Removed, and the Notes paragraph claiming those two workflows "exist only on `main`" replaced: neither exists anywhere, and the real difference is the reverse, `develop` carrying `ios-integration-attempt.yml` that `main` lacks. - **`fastlane/metadata/android/.../changelogs/` is in use again.** The page said to treat it as unused on the strength of a stale `12.txt`; `63.txt` now holds the 2.2.0 notes. The item now says to write the file, and that the pipeline still does not upload it. - The version-bump example moves from `2.0.2`/`+61` to `2.2.0`/`+63`. Refs #991 * docs(releasing): make the upstream issue references clickable Copilot: `fastlane#22204` does not auto-link across repositories, so the tracking issues behind the Play upload defect were unreachable from the page that tells a releaser to work around it. Full URLs for both fastlane issues and the expo one. (cherry picked from commit 9a9282b)
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Found by the
docs/audit. This is the one worth landing before 2.2.0 is cut, because the runbook misdescribes the Android release step and 2.2.0 is the release that will hit it.The dangerous one
The page told the releaser that
android-deployuploads to the Playinternaltrack, so the only manual Android step is promotinginternalto production.It attempts the upload. Since 2.1.0 the bundle declares
android.permission.health.*, and the Play Publishing API rejects health-permission bundles with "You must let us know whether your app includes any health features" regardless of the declaration — #942, a known upstream defect that fastlane closed unfixed and expo/eas-cli reproduced from a different toolchain. The workflow tolerates that one error, emits a::warning::, and writes the recovery steps into the run's step summary.So a green
android-deploydoes not mean a build reached the track. A releaser following the old text would promote an empty internal track and wonder where the build went.The recovery procedure is now on the page — including step 3, reading the console's review warnings before publishing, which is the only place Play reports them and precisely how #959's minSdk regression went unnoticed for eight days.
The one that was false on the day it was written
A whole section described
update-release-fingerprint.ymlopening a PR intodevelopwith the signing SHA-256, anddeploy-site.ymlpublishing Pages. Both workflows and the entiredocs/site/tree were deleted with the project website in #786 on 2026-08-22 — five days before this page was committed. The checklist item "Merge the release-fingerprint PR intodevelop" told the releaser to wait for a PR nothing opens.The Notes paragraph claiming those two workflows "exist only on
main" is replaced. Neither exists anywhere, and the real difference is the reverse:developcarriesios-integration-attempt.yml,maindoes not.The rest
fastlane/metadata/android/en-US/changelogs/is in use again —63.txtlanded this morning with the 2.2.0 notes. The page said to treat the directory as unused on the strength of the stale12.txt.2.0.2/+61to2.2.0/+63.Checked
releasing_doc_test.dartandai_architecture_doc_test.dartboth pass — every relative link and anchor still resolves, including the new#the-android-upload-usually-needs-a-handgit ls-treeonorigin/mainandorigin/developandroid-deployfallback read in full onorigin/release/2.2.0Refs #991, which tracks this file among three docs describing code that has moved.