Scale computer-use 2.0 with open-source drivers, cross-OS sandboxes, and benchmarks for training, evaluation, and data generation.
Rust agentai-agentapplecomputer-usecomputer-use-agentcontainerizationcuadesktop-automationhacktoberfestlumemacosmanusoperatorswiftvirtualizationvirtualization-frameworkwindowswindows-sandbox
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.pynew file mode 100644index 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.pynew file mode 100644index 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.ymlnew file mode 100644index 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.mdnew file mode 100644index 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.