Upstream patches¶
For maintainers: how the images get upstream pull requests before Mozilla releases them, and how to add, update and remove one. Which patches the images have today, and how to read their label: Upstream patches.
How it works¶
The images are built from Mozilla's releases: fxa.yml builds mozilla/fxa for fxa-mono, syncstorage-rs.yml builds mozilla-services/syncstorage-rs. upstream-patches.yml lists the upstream pull requests this project needs now. Its header describes every field.
- In both workflows, the job that picks the release runs tests/test_upstream_patches.py and lists what is to apply.
- Each build applies it with .github/scripts/upstream-patches.py to the checked out release, for every architecture: exactly
base...shaof each entry (or of its release pin for that release), never newer commits of the pull request. - The image gets the list in its label
org.firefox-sync.upstream-patches, and the run's summary shows it. - The tests then run on those images, as always.
On a branch the images are built and tested, not published. Merged into main, a change of upstream-patches.yml rebuilds the current release of the component with it, under the same tags (a new digest). A manual run on main does the same.
- fxa.yml rebuilds when the published image was built for another plan (its label
org.firefox-sync.upstream-patches-plan). Upstream's code runs in build jobs without write access, which hand an OCI archive to push jobs. These push it under tags of the run (fxa-mono-<release>-linux-<arch>-run<id>, the same for the pairing server), the tests use those digests, and main publishes the multi-arch tags from them. - syncstorage-rs.yml has the patches in the key of the images it reuses, with the files of their ports. It writes the tags main reuses (keys, per-architecture tags, build cache) from main only; a branch gets key tags of its own, and reuses main's image when the key is the same (Releasing).
Both run one at a time per branch.
Add a pull request¶
- Review the pull request at the commit to apply.
-
Pin it: its head repository, the full sha of the reviewed head commit, and of its merge base.
gh api repos/<repo>/pulls/<pr> --jq '.head.repo.full_name, .head.sha, .base.sha' gh api repos/<repo>/compare/<base.sha>...<head.sha> --jq .merge_base_commit.sha # base -
Add the entry to upstream-patches.yml, with why, and what to undo here once it is released (
when_released). - Push to a branch: the images are built and tested with it.
A pull request that moves, is rebased or retargeted changes nothing until the entry does. To update one, review the new commits and move sha (and base if it was rebased): again a rebuild.
Rebase one of our pull requests¶
Upstream pull requests target upstream main, which runs ahead of the releases: rebased on it, a pull request can stop applying to the release built here. In the same sitting as the rebase:
- Note the head before the force push (
gh api repos/<repo>/pulls/<pr> --jq .head.sha) and itsbase. Afterwards it is thebeforeCommitof the force push in the pull request's timeline. - Move the entry's
baseandshato the new head. - If the new head no longer applies to the release built here, pin the old head for that release under
releases(see below). Check withupstream-patches.py applyon a clone of the release.
A merged pull request¶
When Mozilla merges its own version of a change we carry (a pull request of theirs, not ours), the entry can point at theirs until a release has it: their pull request, head_repo their repository (a branch of mozilla/fxa is mozilla/fxa), sha its head and base the parent of its first commit. Merged and not in the release built, it is applied as an open one is; once a release has it, the run flags the entry for removal. Close ours as superseded.
Entries are applied in the order of the file. A pull request made on top of another one (its base has the other's changes) comes after it. mozilla/fxa#21709 (the mysql2 driver, Mozilla's version of our mozilla/fxa#21554) is applied before mozilla/fxa#21731, which fixes the patcher with that driver.
Release pins¶
releases maps a release tag to another commit of the same pull request, with its own base:
releases:
v1.348.5:
base: 3e2cb676f8c561e7c293d44ec979c3be88eb81cb
sha: a99361eb6229441aa1214a5d6acdf310cc925e02
- Building that release, the pin's
base...shais applied instead of the entry's. It is a commit of the pull request, so the label is its own...@<base>..<sha>, with no+<release>. - The pinned
shamust have been a head of the pull request: in its history now, or a head before a force push (beforeCommitorafterCommitof the pull request's force pushes, from GraphQL).basemust be an ancestor of it. The entry's ownbaseandshaare checked as always. - GitHub keeps serving such commits through the pull request for now (
compare base...sha). If it no longer does, the build fails: save the change as a port instead. - Any other release gets the entry's
base...sha. When that does not apply, the build tries the pin of the newest older release withgit apply --check, then the newest older port. Whatever applies cleanly first is used, and the run warns: review it on the new release and pin it for that release. - A release pin that does not apply to its own release fails the build, as a port that does not apply does.
mozilla/fxa#21554 had a release pin for v1.348.5: the pull request was rebased on a main that removed a script it changed (backfill-account-authorizations-v2) and changed fxa-auth-server's package.json, so its new head no longer applied to that release. The pin was its head before the rebase. Its entry now points at mozilla/fxa#21709, Mozilla's own version of the change, see A merged pull request.
Per-release ports¶
ports names a directory of this repository with <release-tag>.diff files: the same change made by hand for a release that no commit of the pull request applies to, for example when the code moved between that release and the pull request's base. When a commit of the pull request applies, prefer a release pin: it is the reviewed change itself.
- Building that release, the file is applied instead (before a release pin for it), and the label says so:
...@base..sha+<release-tag>. - Any other release gets its release pin or
base...shaas always. Whenbase...shadoes not apply and no older release pin does, the build tries the newest port of an older release withgit apply --check. If it applies cleanly it is used, the label names that port (+v1.347.3on a later release), and the run warns: review the change on the new release and add its port. If nothing applies, the build fails: add a release pin or a port, or rebase the pull request. - Review a port like the pull request: the release's code, the same change.
(mozilla/fxa#21554 had ports for v1.347.3, where the shared database code was still in packages/fxa-shared, and v1.349.0.)
What a run says¶
| The pull request | What happens |
|---|---|
| open, or merged after the release that is built | applied, and the build goes on. A notice if it has commits after the pinned sha: they are not applied until sha moves |
| merged and in the release (or its changes already in the sources) | not applied; the image is built from the release as it is. After publishing, the job upstream-patches fails with the entry and its when_released. Publishing is not held back |
closed without merging, another head repository, a sha not in its history, a release pin that was never a head of it or that GitHub no longer serves, changes that don't apply to the release, or merged and released but its changes not in the sources |
the build fails and nothing is published. Decide: another pull request, a rebase and a new sha, a release pin or a port, or remove the entry and its workaround |
Remove an entry¶
In one commit: the entry (its release pins with it), what its when_released says, and its ports directory if it has one. A red upstream-patches job is the reminder.
A release pin, or a port, that no release built here needs any more (the entry's base...sha applies to the release built) can go on its own.
An accounts pull request that prepare_environment.sh and the tests look for in the label (mozilla/fxa#21494, mozilla/fxa#21709) also gets a line in config/fxa/fixed-in: the pull request and the first release with it. Without it, the images built after the removal, which no longer list it, would count as images without it.
In the tests¶
Tests that work around an upstream bug read the label. The accounts' tests (tests/e2e-fxa.sh, tests/podman.sh, tests/helm-fxa.sh, tests/fxa-upgrade.sh) decide with tests/fxa_fix.sh, as prepare_environment.sh does: the label, or config/fxa/fixed-in. tests/prepare_functions.sh checks both. tests/e2e.sh skips upstream's test_node_assignment.py::test_user_creation on MariaDB only for images without mozilla-services/syncstorage-rs#2638.
Run it locally¶
The unit tests, on fixtures, with no network:
python3 tests/test_upstream_patches.py
Against the real pull requests (read-only, gh signed in):
python3 .github/scripts/upstream-patches.py plan fxa-mono v1.347.3
python3 .github/scripts/upstream-patches.py apply <component> <tag> <checkout> # on a clone of the release