Skip to content

armgit / cua

Public Imported from GitHub
0

Scale computer-use 2.0 with open-source drivers, cross-OS sandboxes, and benchmarks for training, evaluation, and data generation.

ci(spaces): staged rollout workflow, 10/50/100 or pause (CUA-2069) (#5729)

Francesco Bonacci1fa2247ae745
diff --git a/.github/scripts/release_rollout.py b/.github/scripts/release_rollout.py
new file mode 100644
index 0000000000..e742fd5835
--- /dev/null
+++ b/.github/scripts/release_rollout.py
@@ -0,0 +1,215 @@
+#!/usr/bin/env python3
+"""Staged rollout of a Cua Spaces build: edit the updater feeds, nothing else.
+
+Reads the feed files from --feed-dir (a copy of the assets on the rolling
+`cua-spaces-latest` release), writes the changed ones to --out-dir and prints
+a Markdown report with the diff. It never uploads; .github/workflows/release-rollout.yml
+does that, unless it is a dry run.
+
+electron-updater feeds (latest*.yml, beta*.yml for --channel beta): the top-level
+`stagingPercentage` field. 10 and 50 set it, 100 removes it, pause sets 0 (no
+install is inside 0%, so nobody is offered the version; installs that already
+updated keep it). Pause and resume need no earlier feed file.
+
+Sparkle appcast (macOS, cua-spaces-appcast.xml): the newest item of the channel
+gets `sparkle:phasedRolloutInterval` and a `pubDate`. Sparkle has 7 groups, each
+install picks one at random, and group k is offered the item once
+now >= pubDate + k * interval. So the stages are:
+ 10 pubDate = now, interval = 10 years: group 0 only (1/7 = 14.3%), held
+ 50 pubDate = now - 3 weeks, interval = 1 week: groups 0-3 (4/7 = 57.1%); group 4 follows in a week
+ 100 the interval is removed: everyone
+ pause the item is removed (kept in cua-spaces-appcast-paused.xml); the next stage restores it
+"""
+
+from __future__ import annotations
+
+import argparse
+import difflib
+import io
+import re
+import sys
+import xml.etree.ElementTree as ET
+from datetime import datetime, timedelta, timezone
+from pathlib import Path
+
+SP = "http://www.andymatuschak.org/xml-namespaces/sparkle"
+ET.register_namespace("sparkle", SP)
+APPCAST = "cua-spaces-appcast.xml"
+PAUSED = "cua-spaces-appcast-paused.xml"
+HOLD_SECONDS = 10 * 365 * 24 * 3600
+WEEK = 7 * 24 * 3600
+GROUPS = 7
+STAGING = {"10": "10", "50": "50", "pause": "0"}
+
+ELECTRON_FILES = {
+ "windows": ["{c}.yml"],
+ "linux": ["{c}-linux.yml", "{c}-linux-arm64.yml"],
+ "macos": ["{c}-mac.yml"], # Electron macOS only exists after the Sparkle cutover
+}
+
+
+class RolloutError(Exception):
+ pass
+
+
+def set_staging(text: str, value: str | None) -> str:
+ """The feed with its top-level stagingPercentage set to value, or removed for None."""
+ kept = [line for line in text.splitlines() if not re.match(r"stagingPercentage\s*:", line)]
+ if value is not None:
+ kept.append(f"stagingPercentage: {value}")
+ return "\n".join(kept) + "\n"
+
+
+def feed_version(text: str) -> str:
+ m = re.search(r"^version:\s*['\"]?([^'\"\s]+)", text, re.M)
+ if not m:
+ raise RolloutError("feed has no version")
+ return m.group(1)
+
+
+def electron(feed_dir: Path, channel: str, platforms: list[str], stage: str) -> tuple[dict[str, str], list[str]]:
+ changed: dict[str, str] = {}
+ notes: list[str] = []
+ prefix = "latest" if channel == "stable" else "beta"
+ for platform in platforms:
+ for pattern in ELECTRON_FILES[platform]:
+ name = pattern.format(c=prefix)
+ path = feed_dir / name
+ if not path.exists():
+ notes.append(f"`{name}`: not on the feed, skipped")
+ continue
+ before = path.read_text()
+ version = feed_version(before)
+ if channel == "stable" and "-" in version:
+ raise RolloutError(f"{name} names {version}, a prerelease: the stable feed must not")
+ changed[name] = set_staging(before, None if stage == "100" else STAGING[stage])
+ notes.append(f"`{name}`: version {version}")
+ return changed, notes
+
+
+def _version_key(item: ET.Element) -> tuple[int, ...]:
+ return tuple(int(p) for p in re.findall(r"\d+", item.findtext(f"{{{SP}}}version") or "0"))
+
+
+def _channel_items(root: ET.Element, channel: str) -> list[ET.Element]:
+ want = None if channel == "stable" else "beta"
+ return [i for i in root.iter("item") if i.findtext(f"{{{SP}}}channel") == want]
+
+
+def _write(tree: ET.ElementTree) -> str:
+ ET.indent(tree, space=" ")
+ buf = io.BytesIO()
+ tree.write(buf, encoding="utf-8", xml_declaration=True)
+ return buf.getvalue().decode()
+
+
+def _fmt(dt: datetime) -> str:
+ return dt.astimezone(timezone.utc).strftime("%a, %d %b %Y %H:%M:%S +0000")
+
+
+def sparkle(feed_dir: Path, channel: str, stage: str, now: datetime) -> tuple[dict[str, str], list[str], list[str]]:
+ path = feed_dir / APPCAST
+ if not path.exists():
+ return {}, [f"`{APPCAST}`: not on the feed, skipped"], []
+ tree = ET.parse(path)
+ root = tree.getroot()
+ channel_el = root.find("channel")
+ paused_path = feed_dir / PAUSED
+ deletions: list[str] = []
+ changed: dict[str, str] = {}
+ notes: list[str] = []
+
+ items = _channel_items(root, channel)
+ if stage != "pause" and paused_path.exists():
+ # Resume: put the paused item back before staging it.
+ paused = _channel_items(ET.parse(paused_path).getroot(), channel)
+ if paused and not any(i.findtext(f"{{{SP}}}version") == paused[0].findtext(f"{{{SP}}}version") for i in items):
+ channel_el.insert(len([c for c in channel_el if c.tag != "item"]), paused[0])
+ items = _channel_items(root, channel)
+ notes.append(f"restored the paused item {paused[0].findtext('title')}")
+ deletions.append(PAUSED)
+ if not items:
+ return {}, notes + [f"`{APPCAST}`: no {channel} item, skipped"], deletions
+ item = max(items, key=_version_key)
+ title = item.findtext("title")
+ if channel == "stable" and title and "-" in title:
+ raise RolloutError(f"newest stable appcast item is {title}, a prerelease")
+
+ for el in item.findall(f"{{{SP}}}phasedRolloutInterval"):
+ item.remove(el)
+
+ if stage == "pause":
+ channel_el.remove(item)
+ keep = ET.ElementTree(ET.fromstring(f"<rss xmlns:sparkle='{SP}' version='2.0'><channel/></rss>"))
+ keep.getroot().find("channel").append(item)
+ changed[PAUSED] = _write(keep)
+ notes.append(f"`{APPCAST}`: {title} removed, kept in `{PAUSED}`")
+ elif stage == "100":
+ notes.append(f"`{APPCAST}`: {title} phased rollout removed, every install is offered it")
+ else:
+ interval, pub_date = (HOLD_SECONDS, now) if stage == "10" else (WEEK, now - timedelta(seconds=3 * WEEK))
+ pub = item.find("pubDate")
+ if pub is None:
+ pub = ET.Element("pubDate")
+ item.insert(list(item).index(item.find("title")) + 1, pub)
+ pub.text = _fmt(pub_date)
+ ph = ET.Element(f"{{{SP}}}phasedRolloutInterval")
+ ph.text = str(interval)
+ item.insert(list(item).index(pub) + 1, ph)
+ groups = 1 if stage == "10" else 4
+ notes.append(f"`{APPCAST}`: {title}, {groups} of {GROUPS} groups ({groups / GROUPS:.1%}) are offered it now")
+ notes.append(
+ "held there until the next stage"
+ if stage == "10"
+ else "Sparkle adds a group every 7 days after this, so 100% arrives by itself within 3 weeks unless paused"
+ )
+ changed[APPCAST] = _write(tree)
+ return changed, notes, deletions
+
+
+def main(argv: list[str] | None = None) -> int:
+ ap = argparse.ArgumentParser(description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)
+ ap.add_argument("--feed-dir", required=True, type=Path)
+ ap.add_argument("--out-dir", required=True, type=Path)
+ ap.add_argument("--channel", choices=["stable", "beta"], default="stable")
+ ap.add_argument("--platform", choices=["macos", "windows", "linux", "all"], required=True)
+ ap.add_argument("--stage", choices=["10", "50", "100", "pause"], required=True)
+ ap.add_argument("--now", help="ISO time (tests)")
+ a = ap.parse_args(argv)
+ now = datetime.fromisoformat(a.now) if a.now else datetime.now(timezone.utc)
+ platforms = ["macos", "windows", "linux"] if a.platform == "all" else [a.platform]
+
+ try:
+ changed, notes = electron(a.feed_dir, a.channel, platforms, a.stage)
+ deletions: list[str] = []
+ if "macos" in platforms:
+ sp_changed, sp_notes, deletions = sparkle(a.feed_dir, a.channel, a.stage, now)
+ changed.update(sp_changed)
+ notes += sp_notes
+ except RolloutError as e:
+ print(f"::error::{e}")
+ return 1
+
+ a.out_dir.mkdir(parents=True, exist_ok=True)
+ out = [f"### {a.channel} feed, {a.platform}, stage {a.stage}", ""]
+ out += [f"- {n}" for n in notes] + [""]
+ any_diff = False
+ for name, new in sorted(changed.items()):
+ old_path = a.feed_dir / name
+ old = old_path.read_text() if old_path.exists() else ""
+ diff = list(difflib.unified_diff(old.splitlines(), new.splitlines(), f"a/{name}", f"b/{name}", lineterm="", n=2))
+ if not diff:
+ out.append(f"`{name}`: no change")
+ continue
+ any_diff = True
+ (a.out_dir / name).write_text(new)
+ out += [f"`{name}`", "", "```diff", *diff, "```", ""]
+ (a.out_dir / "deletions.txt").write_text("".join(f"{d}\n" for d in deletions))
+ if not any_diff and not deletions:
+ out.append("Nothing to change.")
+ print("\n".join(out))
+ return 0
+
+
+if __name__ == "__main__":
+ sys.exit(main())
diff --git a/.github/scripts/tests/test_release_rollout.py b/.github/scripts/tests/test_release_rollout.py
new file mode 100644
index 0000000000..28b79e344b
--- /dev/null
+++ b/.github/scripts/tests/test_release_rollout.py
@@ -0,0 +1,103 @@
+"""Run: python3 .github/scripts/tests/test_release_rollout.py"""
+
+import contextlib
+import io
+import sys
+import tempfile
+import unittest
+from datetime import datetime, timezone
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).resolve().parents[1]))
+import release_rollout as rr # noqa: E402
+
+NOW = datetime(2026, 10, 23, 12, 0, tzinfo=timezone.utc)
+YML = "version: 0.13.1\nfiles:\n - url: https://x/a.exe\npath: https://x/a.exe\nreleaseDate: '2026-10-22T00:00:00Z'\n"
+APPCAST = """<?xml version='1.0' encoding='utf-8'?>
+<rss xmlns:sparkle="http://www.andymatuschak.org/xml-namespaces/sparkle" version="2.0">
+ <channel>
+ <title>Cua Spaces</title>
+ <item><title>0.13.1</title><pubDate>Thu, 22 Oct 2026 15:12:41 +0000</pubDate><sparkle:version>0.13.1.96</sparkle:version></item>
+ <item><title>0.13.0</title><pubDate>Thu, 22 Oct 2026 05:36:29 +0000</pubDate><sparkle:version>0.13.0.95</sparkle:version></item>
+ <item><title>0.14.0-beta.1</title><sparkle:channel>beta</sparkle:channel><sparkle:version>0.14.0.97</sparkle:version></item>
+ </channel>
+</rss>
+"""
+
+
+def run(files, stage, platform="all", channel="stable"):
+ with tempfile.TemporaryDirectory() as d:
+ feed, out = Path(d, "in"), Path(d, "out")
+ feed.mkdir()
+ for name, text in files.items():
+ (feed / name).write_text(text)
+ with contextlib.redirect_stdout(io.StringIO()):
+ code = rr.main(["--feed-dir", str(feed), "--out-dir", str(out), "--platform", platform,
+ "--stage", stage, "--channel", channel, "--now", NOW.isoformat()])
+ return code, ({p.name: p.read_text() for p in out.iterdir()} if out.exists() else {})
+
+
+class Electron(unittest.TestCase):
+ def test_stages(self):
+ for stage, want in (("10", "stagingPercentage: 10"), ("50", "stagingPercentage: 50"), ("pause", "stagingPercentage: 0")):
+ _, out = run({"latest.yml": YML}, stage, "windows")
+ self.assertTrue(out["latest.yml"].endswith(want + "\n"))
+
+ def test_100_removes_the_field_and_replaces_not_appends(self):
+ _, out = run({"latest.yml": YML + "stagingPercentage: 10\n"}, "100", "windows")
+ self.assertNotIn("stagingPercentage", out["latest.yml"])
+ _, out = run({"latest.yml": YML + "stagingPercentage: 10\n"}, "50", "windows")
+ self.assertEqual(out["latest.yml"].count("stagingPercentage"), 1)
+
+ def test_stable_refuses_a_prerelease_feed(self):
+ code, _ = run({"latest.yml": YML.replace("0.13.1", "0.14.0-beta.1")}, "10", "windows")
+ self.assertEqual(code, 1)
+
+ def test_beta_touches_only_beta_files(self):
+ _, out = run({"latest.yml": YML, "beta.yml": YML.replace("0.13.1", "0.14.0-beta.1")}, "10", "windows", "beta")
+ self.assertIn("beta.yml", out)
+ self.assertNotIn("latest.yml", out)
+
+ def test_platform_selects_files(self):
+ _, out = run({"latest.yml": YML, "latest-linux.yml": YML, "latest-linux-arm64.yml": YML}, "10", "linux")
+ self.assertEqual(sorted(k for k in out if k.endswith(".yml")), ["latest-linux-arm64.yml", "latest-linux.yml"])
+
+
+class Sparkle(unittest.TestCase):
+ def test_10_holds_group_zero_on_the_newest_stable_item_only(self):
+ _, out = run({rr.APPCAST: APPCAST}, "10", "macos")
+ xml = out[rr.APPCAST]
+ self.assertEqual(xml.count("phasedRolloutInterval>"), 2) # one open, one close tag
+ self.assertIn(f"<sparkle:phasedRolloutInterval>{rr.HOLD_SECONDS}<", xml)
+ self.assertIn("Fri, 23 Oct 2026 12:00:00 +0000", xml)
+
+ def test_50_opens_four_groups(self):
+ _, out = run({rr.APPCAST: APPCAST}, "50", "macos")
+ self.assertIn(f">{rr.WEEK}<", out[rr.APPCAST])
+ self.assertIn("Fri, 02 Oct 2026 12:00:00 +0000", out[rr.APPCAST]) # now - 3 weeks
+
+ def test_100_removes_the_interval(self):
+ _, staged = run({rr.APPCAST: APPCAST}, "10", "macos")
+ _, out = run({rr.APPCAST: staged[rr.APPCAST]}, "100", "macos")
+ self.assertNotIn("phasedRolloutInterval", out[rr.APPCAST])
+
+ def test_pause_removes_item_and_resume_restores_it(self):
+ _, out = run({rr.APPCAST: APPCAST}, "pause", "macos")
+ self.assertNotIn("<title>0.13.1</title>", out[rr.APPCAST])
+ self.assertIn("0.13.0", out[rr.APPCAST])
+ self.assertIn("0.14.0-beta.1", out[rr.APPCAST]) # beta untouched
+ self.assertIn("<title>0.13.1</title>", out[rr.PAUSED])
+ _, back = run({rr.APPCAST: out[rr.APPCAST], rr.PAUSED: out[rr.PAUSED]}, "10", "macos")
+ self.assertIn("<title>0.13.1</title>", back[rr.APPCAST])
+ self.assertIn(rr.PAUSED, back["deletions.txt"])
+
+ def test_beta_rehearsal_picks_the_beta_item(self):
+ _, out = run({rr.APPCAST: APPCAST}, "10", "macos", "beta")
+ xml = out[rr.APPCAST]
+ self.assertEqual(xml.count("phasedRolloutInterval>"), 2)
+ beta = xml.split("0.14.0-beta.1")[1]
+ self.assertIn("phasedRolloutInterval", beta)
+
+
+if __name__ == "__main__":
+ unittest.main()
diff --git a/.github/workflows/release-rollout.yml b/.github/workflows/release-rollout.yml
new file mode 100644
index 0000000000..f07bc30586
--- /dev/null
+++ b/.github/workflows/release-rollout.yml
@@ -0,0 +1,123 @@
+name: "Release: staged rollout (Cua Spaces)"
+
+# Moves a published stable Cua Spaces build through 10% -> 50% -> 100% of
+# installs, or pauses it (CUA-2069, phase 4 of CUA-1991; design in
+# trycua/cua#5704, "Staged rollout"). It only edits the updater feeds on the
+# rolling `cua-spaces-latest` release; it never builds or publishes a release.
+#
+# electron-updater (Windows, Linux, Electron macOS): `stagingPercentage` in
+# latest*.yml. 100 removes it, pause sets 0.
+# Sparkle (macOS): `sparkle:phasedRolloutInterval` on the newest stable
+# appcast item. 100 removes it, pause removes the item (kept for resume).
+#
+# The edits and what they mean for users: .github/scripts/release_rollout.py and
+# apps/cua-spaces-desktop/docs/staged-rollout.md (also the beta rehearsal).
+# Stable only by default; `channel: beta` exists to rehearse on the beta feed.
+# `dry_run` (the default) prints the feed diff and uploads nothing. The actor
+# and the reason go to the job summary. The release workflow still publishes
+# feeds as before; writing them at 10% on publish comes with phase 2.
+
+on:
+ workflow_dispatch:
+ inputs:
+ component:
+ description: "Component"
+ type: choice
+ options: [spaces]
+ default: spaces
+ platform:
+ description: "Platform"
+ type: choice
+ options: [all, macos, windows, linux]
+ default: all
+ stage:
+ description: "Share of installs offered the update (pause: none)"
+ type: choice
+ options: ["10", "50", "100", pause]
+ reason:
+ description: "Why (logged in the job summary)"
+ type: string
+ required: true
+ channel:
+ description: "Feed (stable; beta only to rehearse)"
+ type: choice
+ options: [stable, beta]
+ default: stable
+ dry_run:
+ description: "Print the feed diff, upload nothing"
+ type: boolean
+ default: true
+
+permissions:
+ contents: write
+
+concurrency:
+ group: release-rollout-spaces
+ cancel-in-progress: false
+
+jobs:
+ rollout:
+ name: "Rollout ${{ inputs.stage }} (${{ inputs.channel }}, ${{ inputs.platform }}${{ inputs.dry_run && ', dry run' || '' }})"
+ runs-on: ubuntu-latest
+ timeout-minutes: 10
+ env:
+ GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+ TAG: cua-spaces-latest
+ steps:
+ - uses: actions/checkout@v4
+ - name: Check the rollout script
+ run: python3 .github/scripts/tests/test_release_rollout.py
+ - name: Record who and why
+ env:
+ REASON: ${{ inputs.reason }}
+ run: |
+ {
+ echo "## Rollout: ${{ inputs.stage }} on ${{ inputs.channel }}, ${{ inputs.platform }}"
+ echo
+ echo "- actor: \`$GITHUB_ACTOR\`"
+ echo "- run: $GITHUB_SERVER_URL/$GITHUB_REPOSITORY/actions/runs/$GITHUB_RUN_ID"
+ echo "- dry run: ${{ inputs.dry_run }}"
+ echo "- reason: $REASON"
+ echo
+ } >> "$GITHUB_STEP_SUMMARY"
+ - name: Fetch the feeds
+ run: |
+ set -euo pipefail
+ mkdir -p feed
+ for pattern in 'latest*.yml' 'beta*.yml' cua-spaces-appcast.xml cua-spaces-appcast-paused.xml; do
+ gh release download "$TAG" --pattern "$pattern" --dir feed --clobber --repo "$GITHUB_REPOSITORY" 2>/dev/null || true
+ done
+ ls -l feed
+ [ -n "$(ls feed)" ] || { echo "::error::no feed files on $TAG"; exit 1; }
+ - name: Edit the feeds
+ run: |
+ set -euo pipefail
+ python3 .github/scripts/release_rollout.py --feed-dir feed --out-dir out \
+ --channel "${{ inputs.channel }}" --platform "${{ inputs.platform }}" --stage "${{ inputs.stage }}" \
+ | tee report.md >> "$GITHUB_STEP_SUMMARY"
+ [ "${PIPESTATUS[0]}" = 0 ]
+ shopt -s nullglob
+ for f in out/*.xml; do xmllint --noout "$f"; done
+ - name: Upload the feeds
+ if: ${{ !inputs.dry_run }}
+ run: |
+ set -euo pipefail
+ shopt -s nullglob
+ files=(out/*.yml out/*.xml)
+ if [ ${#files[@]} -gt 0 ]; then
+ gh release upload "$TAG" "${files[@]}" --clobber --repo "$GITHUB_REPOSITORY"
+ fi
+ while read -r name; do
+ [ -n "$name" ] && gh release delete-asset "$TAG" "$name" --yes --repo "$GITHUB_REPOSITORY"
+ done < out/deletions.txt
+ # Read back what is live.
+ mkdir -p live
+ for f in "${files[@]}"; do
+ gh release download "$TAG" --pattern "$(basename "$f")" --dir live --clobber --repo "$GITHUB_REPOSITORY"
+ cmp "$f" "live/$(basename "$f")"
+ done
+ echo "Uploaded: ${files[*]:-nothing}" >> "$GITHUB_STEP_SUMMARY"
+ - name: Dry run note
+ if: ${{ inputs.dry_run }}
+ run: |
+ echo "Dry run, nothing was uploaded. Run again with dry_run off to apply this diff." >> "$GITHUB_STEP_SUMMARY"
diff --git a/apps/cua-spaces-desktop/docs/staged-rollout.md b/apps/cua-spaces-desktop/docs/staged-rollout.md
new file mode 100644
index 0000000000..882a228d0b
--- /dev/null
+++ b/apps/cua-spaces-desktop/docs/staged-rollout.md
@@ -0,0 +1,119 @@
+# Staged rollout of Cua Spaces stable builds
+
+CUA-2069, phase 4 of CUA-1991 (design: trycua/cua#5704, "Staged rollout").
+A stable build is offered to a share of installs first. If it is bad, pause it
+before everyone has it.
+
+Run **Actions > Release: staged rollout (Cua Spaces)**. It edits only the feed
+files on the rolling `cua-spaces-latest` release. Inputs:
+
+| Input | Values |
+|---|---|
+| `component` | `spaces` |
+| `platform` | `all`, `macos`, `windows`, `linux` |
+| `stage` | `10`, `50`, `100`, `pause` |
+| `reason` | free text, logged with the actor in the job summary |
+| `channel` | `stable` (default), `beta` (rehearsal only) |
+| `dry_run` | on by default: prints the feed diff, uploads nothing |
+
+Typical flow after a stable release: `10`, watch crash and update telemetry,
+`50`, `100`. Bad build: `pause`. The release workflow still publishes feeds as
+before (everyone); writing them at 10% on publish comes with phase 2.
+
+## What each stage does
+
+| Stage | electron-updater (Windows, Linux) | Sparkle (macOS) |
+|---|---|---|
+| `10` | `stagingPercentage: 10` | newest stable item gets `pubDate` = now and a 10-year `phasedRolloutInterval`: group 0 of 7 only, 14.3% |
+| `50` | `stagingPercentage: 50` | `pubDate` = 3 weeks ago, interval 1 week: groups 0 to 3, 57.1%. Group 4 follows a week later |
+| `100` | field removed | interval removed |
+| `pause` | `stagingPercentage: 0` | item removed from the appcast (kept in `cua-spaces-appcast-paused.xml`) |
+
+Resuming (`10`, `50`, `100` after `pause`) restores the paused Sparkle item
+first. Installs that already took the update keep it in every case: neither
+updater downgrades.
+
+## Research (primary sources)
+
+### electron-updater `stagingPercentage` (we ship 6.8.9)
+
+Source: `AppUpdater.ts` in electron-builder, `isStagingMatch` and
+`getOrCreateStagingUserId`.
+
+- Each install makes one random UUID the first time it needs it and stores it
+ in `<userData>/.updaterId`. It is stable across launches and updates, and
+ lost only if the user data folder is deleted (a reinstall that keeps the
+ folder keeps the id).
+- The check: take the last 4 bytes of the UUID as a number, divide by
+ `0xffffffff` to get a fixed position `p` in [0, 1), and the install is
+ offered the update when `p < stagingPercentage / 100`. So the groups are
+ nested: the 10% that got it stay inside the 50%, and 100% adds the rest. A
+ missing or non-numeric `stagingPercentage` means everyone.
+- It is evaluated on every check, so lowering the number later stops offering
+ the update to installs that have not downloaded it. `0` offers it to nobody.
+- The updater sends the id as an `x-user-staging-id` request header, so a
+ server could use it. GitHub release downloads ignore it.
+- Pause and rollback: nothing is undone on installs that already updated, and
+ `allowDowngrade` is false in our updater (`src/updater.ts`). Rolling back
+ means shipping a newer fixed version. An update already downloaded and
+ waiting for `autoInstallOnAppQuit` is not cancelled by a later feed change.
+- electron-builder can write `stagingPercentage` itself, but we edit the
+ uploaded feed text instead, so the percentage changes without a rebuild.
+- Choice for pause: the design note said "restore the previous feed file".
+ Nothing keeps previous feed files today, and `stagingPercentage: 0` has the
+ same effect for clients without needing one, and resumes cleanly.
+
+### Sparkle phased rollout (we ship 2.10.0, `Package.swift`)
+
+Sources: sparkle-project.org publishing docs ("Phased group rollouts"),
+`SUPhasedUpdateGroupInfo.m`, `SUAppcastDriver.m` (`itemIsReadyForPhasedRollout`),
+`SUAppcastItem.h` (needs Sparkle 1.25 or later, so 2.10.0 supports it).
+
+- An item needs a `pubDate` and `<sparkle:phasedRolloutInterval>` (seconds).
+- Sparkle hardcodes 7 groups. Each install stores a random number in user
+ defaults (`SUUpdateGroupIdentifier`) and its group is that number mod 7. The
+ id is not sent to a server and is re-generated after an update is
+ downloaded.
+- Group `k` is offered the item once `now >= pubDate + k * interval`. So the
+ share offered over time is 1/7, 2/7 ... 7/7 (14%, 29%, 43%, 57%, 71%, 86%,
+ 100%), by time, not by a number we pick.
+- Phased rollout does not apply to critical updates, nor when the user
+ checks manually (Check for Updates...): those see the update at once.
+- Pause: removing the item from the appcast. Sparkle cannot downgrade, so
+ installs that updated stay. Rollback is a fixed higher-numbered release.
+- Our appcast has no feed-level signature (only per-item EdDSA on the disk
+ image), so editing the XML needs no re-signing.
+
+**Matching 10/50/100.** Not exactly, but closely, by choosing the interval and
+`pubDate` ourselves per stage instead of leaving the clock to run: a huge
+interval pins the offer to group 0 (14.3%, the "10%" stage); an interval of one
+week with `pubDate` three weeks back opens groups 0 to 3 (57.1%, the "50%"
+stage); removing the interval is 100%. The limits are that 14% is not 10%, and
+that the 50% stage is only held for a week: Sparkle opens group 4 after that
+unless someone advances or pauses. Manual update checks bypass the stages.
+
+**Recommended settings:** electron-updater 10, 50, 100 as is. Sparkle through
+this workflow's mapping above (about 14%, 57%, 100%); a 7-day gate between
+stages is the default cadence for macOS, and the 50% stage should not be left
+unattended past a week. Accept the difference, no custom update server.
+
+## Rehearsal on the beta feed
+
+Beta stays at 100% in production. To rehearse without touching stable, use
+`channel: beta`; it only edits `beta*.yml` and the newest `beta` appcast item,
+which only apps on "Update to: Beta" read.
+
+1. Dry run first: `channel: beta`, `platform: all`, `stage: 10`,
+ `dry_run: true`. Read the diff in the job summary (expect
+ `stagingPercentage: 10` in `beta*.yml`, one `phasedRolloutInterval` on the
+ newest beta item).
+2. Run it for real (`dry_run: false`). On a test install of the beta app on
+ Windows or Linux, set the Update channel to Beta, then
+ `curl -L https://github.com/trycua/cua/releases/download/cua-spaces-latest/beta.yml`
+ shows the field; the updater log prints `Staging percentage: 0.1, percentage: ...`.
+3. `stage: pause`, check the beta appcast item is gone and `stagingPercentage: 0`
+ is set, then `stage: 100` and check the item is back with no interval.
+4. Always end on `stage: 100` for `channel: beta` so beta is back to everyone.
+ The beta pause sidecar shares the name `cua-spaces-appcast-paused.xml` with
+ stable, so do not have both channels paused at once.
+5. Do not run the workflow on stable until there is a stable release to stage.