From 7d6e7e4b8a59b1deb7bde0aa6f7786f074cf49b1 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Mehmet=20Ali=20Ustao=C4=9Flu?= Date: Sat, 7 Nov 2026 23:24:18 +0100 Subject: [PATCH 1/3] ci: upstream compatibility alerts and auto-publish to pub.dev Upstream compatibility (daily + manual): for each package, test the newest releases within our constraints, and the newest upstream majors when pub outdated reports any, with the same checks as the CI package job, on the newest Flutter stable. When pub upgrade --major-versions cannot reach a new major, `pub add name:^latest` forces it, so the leg tests the new major or reports what blocks it instead of passing on the old one. One issue per package under the upstream-compat label, touched only when its fingerprint changes and closed once the package passes again. Release: after CI succeeds on a push to main, packages whose pubspec version is not on pub.dev (and tops CHANGELOG.md, and is newer than pub.dev) are re-verified with analyze, tests and publish --dry-run, tagged -v, and handed to Publish via workflow_dispatch, because a GITHUB_TOKEN tag push does not trigger workflows. Publish: dart-lang/setup-dart's reusable publish workflow (OIDC) in the pub.dev environment, after checking the tag against pubspec and changelog. --- .github/scripts/release_plan.py | 182 +++++++++++++ .github/scripts/upstream_check.py | 377 ++++++++++++++++++++++++++ .github/scripts/upstream_issues.py | 206 ++++++++++++++ .github/workflows/publish.yml | 84 ++++++ .github/workflows/release.yml | 166 ++++++++++++ .github/workflows/upstream-compat.yml | 148 ++++++++++ .gitignore | 3 + AUTHORING.md | 26 ++ 8 files changed, 1192 insertions(+) create mode 100644 .github/scripts/release_plan.py create mode 100644 .github/scripts/upstream_check.py create mode 100644 .github/scripts/upstream_issues.py create mode 100644 .github/workflows/publish.yml create mode 100644 .github/workflows/release.yml create mode 100644 .github/workflows/upstream-compat.yml diff --git a/.github/scripts/release_plan.py b/.github/scripts/release_plan.py new file mode 100644 index 0000000..ab22db0 --- /dev/null +++ b/.github/scripts/release_plan.py @@ -0,0 +1,182 @@ +#!/usr/bin/env python3 +"""Decide which packages on this commit need publishing to pub.dev. + +A package is a release candidate when its pubspec.yaml version is not on +pub.dev yet. That is the question that matters, rather than "did pubspec.yaml +change in this push": it is the same answer for a squash merge, a merge commit +or a stack of pushes, and a release whose publish failed is picked up again by +the next run instead of being lost with the diff that introduced it. + +For each candidate the version must also be: + - the newest `## ` heading of CHANGELOG.md (an unreleased or missing entry + blocks the release), and + - newer than every version already on pub.dev (publishing an older version + is legal on pub.dev, but never what a merge to main means here — do it by + hand if you really need it). + +A package that is not on pub.dev at all is skipped with a warning: pub.dev +only allows automated publishing for packages that already exist, so the +first version has to go up with `flutter pub publish` by hand. + +Output: a JSON list on stdout, one {package, version, tag, tag_exists} per +candidate. `tag_exists` means an earlier run tagged this version but pub.dev +still does not have it — the publish failed or was never approved — and the +release job re-dispatches publishing instead of tagging again. + +Exits non-zero if any package's metadata is inconsistent, so a bad bump fails +the run in plain sight rather than quietly not publishing. With +--github-output it exits 0 and writes `problems=` instead, so one bad bump +does not hold back the other packages released in the same merge; the +workflow fails the run on that count once they are out. + +Usage: + release_plan.py [--github-output] +""" + +import argparse +import json +import os +import re +import subprocess +import sys +import urllib.error +import urllib.request + +sys.path.insert(0, os.path.dirname(os.path.abspath(__file__))) +from check_repo import ( # noqa: E402 + discover, load_yaml, newest_changelog_version, read_text, +) + +SEMVER = re.compile(r"^(\d+)\.(\d+)\.(\d+)(?:-([0-9A-Za-z.-]+))?(?:\+[0-9A-Za-z.-]+)?$") + + +def tag_for(package, version): + """Must match the tag pattern configured on pub.dev: -v{{version}}.""" + return f"{package}-v{version}" + + +def semver_key(version): + """Sort key with semver precedence: a prerelease sorts below its release.""" + m = SEMVER.match(version) + if not m: + return None + major, minor, patch, pre = m.groups() + pre_key = (1,) if pre is None else (0, *[ + (0, int(p), "") if p.isdigit() else (1, 0, p) for p in pre.split(".") + ]) + return (int(major), int(minor), int(patch), pre_key) + + +def pub_versions(package): + """Published versions, [] if the package does not exist, None on error.""" + url = f"https://pub.dev/api/packages/{package}" + req = urllib.request.Request(url, headers={ + "Accept": "application/vnd.pub.v2+json", + "User-Agent": "fluttertv-plugins-release-plan", + }) + try: + with urllib.request.urlopen(req, timeout=30) as resp: + data = json.load(resp) + except urllib.error.HTTPError as exc: + if exc.code == 404: + return [] + print(f"error: {url}: HTTP {exc.code}", file=sys.stderr) + return None + except (urllib.error.URLError, OSError, ValueError) as exc: + print(f"error: {url}: {exc}", file=sys.stderr) + return None + return [v["version"] for v in data.get("versions", [])] + + +def remote_tags(root): + """Tag names on origin. ls-remote, not local tags: the checkout is shallow + and may not have fetched them.""" + proc = subprocess.run(["git", "ls-remote", "--tags", "origin"], cwd=root, + stdout=subprocess.PIPE, stderr=subprocess.PIPE, text=True) + if proc.returncode != 0: + raise RuntimeError(f"git ls-remote failed: {proc.stderr.strip()}") + tags = set() + for line in proc.stdout.splitlines(): + ref = line.split("\t")[-1] + if ref.startswith("refs/tags/"): + tags.add(ref[len("refs/tags/"):].removesuffix("^{}")) + return tags + + +def plan(root, tags): + candidates, problems = [], [] + for pkg in discover(os.path.join(root, "packages")): + d = os.path.join(root, "packages", pkg) + pubspec, err = load_yaml(os.path.join(d, "pubspec.yaml")) + if err or not isinstance(pubspec, dict): + problems.append(f"{pkg}: pubspec.yaml unreadable ({err})") + continue + if pubspec.get("publish_to") == "none": + continue + name, version = pubspec.get("name"), pubspec.get("version") + if name != pkg: + problems.append(f"{pkg}: pubspec name is '{name}', not the directory name") + continue + if not version or semver_key(version) is None: + problems.append(f"{pkg}: version '{version}' is not semver") + continue + + published = pub_versions(pkg) + if published is None: + problems.append(f"{pkg}: could not read pub.dev — not deciding blind") + continue + if version in published: + continue + if not published: + print(f"::warning::{pkg} is not on pub.dev. Automated publishing only " + f"works for existing packages — publish {version} by hand once.", + file=sys.stderr) + continue + + newest = max((v for v in published if semver_key(v)), key=semver_key, default=None) + if newest and semver_key(version) <= semver_key(newest): + problems.append(f"{pkg}: {version} is not newer than {newest} on pub.dev") + continue + text, err = read_text(os.path.join(d, "CHANGELOG.md")) + top, heading = newest_changelog_version(text) if text is not None else (None, None) + if top != version: + problems.append(f"{pkg}: version {version} but the newest CHANGELOG " + f"heading is '{heading}' — add a '## {version}' entry") + continue + tag = tag_for(pkg, version) + candidates.append({"package": pkg, "version": version, "tag": tag, + "tag_exists": tag in tags}) + return candidates, problems + + +def main(): + parser = argparse.ArgumentParser(description=__doc__.split("\n")[0]) + parser.add_argument("root", nargs="?", default=".") + parser.add_argument("--github-output", action="store_true", + help="also write candidates= to $GITHUB_OUTPUT") + opts = parser.parse_args() + root = os.path.abspath(opts.root) + candidates, problems = plan(root, remote_tags(root)) + for p in problems: + print(f"::error::{p}", file=sys.stderr) + for c in candidates: + note = " (tag exists; re-dispatching publish)" if c["tag_exists"] else "" + print(f"release: {c['package']} {c['version']} as {c['tag']}{note}", + file=sys.stderr) + if not candidates: + print("Nothing to release: every package's version is already on pub.dev.", + file=sys.stderr) + payload = json.dumps(candidates) + print(payload) + if opts.github_output: + with open(os.environ["GITHUB_OUTPUT"], "a", encoding="utf-8") as fh: + fh.write(f"candidates={payload}\n") + fh.write(f"problems={len(problems)}\n") + # In Actions the problems surface through their own job, so the + # healthy candidates on this commit still get released. + return 0 + return 1 if problems else 0 + + +if __name__ == "__main__": + sys.exit(main()) diff --git a/.github/scripts/upstream_check.py b/.github/scripts/upstream_check.py new file mode 100644 index 0000000..76eb9c2 --- /dev/null +++ b/.github/scripts/upstream_check.py @@ -0,0 +1,377 @@ +#!/usr/bin/env python3 +"""Check one package against the newest upstream releases and Flutter. + +Each *_tvos package federates an upstream plugin through its platform +interface (shared_preferences_platform_interface, url_launcher_platform_ +interface, ...), and its example depends on the app-facing upstream package. +Upstream ships on its own schedule, and three kinds of release break us without +any commit here: + + broken Something inside our constraints already fails: a minor + release of a platform interface added an abstract member, or a + new Flutter stable rejects our code. Users hit this today. + + major-breaks A new major is out that our constraint excludes, and moving to + it fails resolution, analysis or tests. Porting work needed. + + lag A new major is out that our constraint excludes, and moving to + it passes. Widening the constraint is the whole fix — but until + then, an app on the new upstream major cannot resolve us. + +A package with none of these is `ok`. The script never edits the repository: +both legs run on scratch copies of packages/ (the whole tree, because +pubspec_overrides.yaml points at siblings such as ../firebase_core_tvos). + +It writes /.json for upstream_issues.py to turn into issues. Its +exit code is about the tooling, not the findings: 0 whenever a report was +written, including for a broken package, so one package's breakage cannot hide +another's. Non-zero means no trustworthy report exists, and the workflow fails +loudly instead of filing an issue about a network blip. + +Usage: + upstream_check.py --out +""" + +import argparse +import hashlib +import json +import os +import re +import shutil +import subprocess +import sys +import tempfile + +sys.path.insert(0, os.path.dirname(os.path.abspath(__file__))) +from check_repo import load_yaml # noqa: E402 + +LOG_TAIL = 80 +STEP_TIMEOUT = 20 * 60 + +# Ignored when copying packages/ to scratch: build output and resolution state +# that would make a scratch run differ from a fresh checkout. +COPY_IGNORE = shutil.ignore_patterns( + ".dart_tool", "build", "pubspec.lock", ".flutter-plugins", + ".flutter-plugins-dependencies", "Pods", ".symlinks", "DerivedData", +) + + +def run(cmd, cwd): + """(ok, combined output). Never raises for a failing command.""" + try: + proc = subprocess.run( + cmd, cwd=cwd, stdout=subprocess.PIPE, stderr=subprocess.STDOUT, + text=True, timeout=STEP_TIMEOUT, + ) + return proc.returncode == 0, proc.stdout + except subprocess.TimeoutExpired as exc: + out = exc.stdout or "" + if isinstance(out, bytes): + out = out.decode("utf-8", "replace") + return False, out + f"\n[timed out after {STEP_TIMEOUT}s]" + except OSError as exc: + return False, f"[could not run {cmd[0]}: {exc}]" + + +def tail(text, n=LOG_TAIL): + lines = text.rstrip().splitlines() + if len(lines) <= n: + return "\n".join(lines) + return f"[... {len(lines) - n} earlier lines omitted]\n" + "\n".join(lines[-n:]) + + +def hosted_deps(pubspec_path, section="dependencies"): + """{name: constraint} for hosted deps in a section, minus overridden ones. + + sdk:, path: and git: dependencies are not ours to upgrade, and neither is + anything pubspec_overrides.yaml pins to a sibling — its "latest" is + whatever the sibling directory says. + """ + pubspec, err = load_yaml(pubspec_path) + if err or not isinstance(pubspec, dict): + return {} + overrides, _ = load_yaml(os.path.join(os.path.dirname(pubspec_path), + "pubspec_overrides.yaml")) + overridden = set() + if isinstance(overrides, dict): + overridden = set((overrides.get("dependency_overrides") or {}).keys()) + overridden |= set((pubspec.get("dependency_overrides") or {}).keys()) + out = {} + for name, spec in (pubspec.get(section) or {}).items(): + if name in overridden: + continue + if isinstance(spec, str) or spec is None: + out[name] = spec or "any" + elif isinstance(spec, dict) and not ({"sdk", "path", "git"} & spec.keys()): + out[name] = spec.get("version", "any") + return out + + +def outdated(pkg_dir): + """Direct hosted deps whose newest release lies outside the constraint. + + `pub outdated` already knows the difference: `upgradable` is the newest + version the current constraints allow, `latest` the newest stable release. + When they differ for a direct dependency, the constraint is what holds us + back. Prereleases are not counted — `latest` excludes them by default. + """ + ok, out = run(["flutter", "pub", "outdated", "--json", + "--no-dev-dependencies"], pkg_dir) + if not ok: + return None, out + start = out.find("{") + try: + data = json.loads(out[start:]) if start >= 0 else {} + except json.JSONDecodeError: + return None, out + wanted = hosted_deps(os.path.join(pkg_dir, "pubspec.yaml")) + rows = [] + for row in data.get("packages", []): + name = row.get("package") + if name not in wanted: + continue + upgradable = (row.get("upgradable") or {}).get("version") + latest = (row.get("latest") or {}).get("version") + if latest and upgradable != latest: + rows.append({"package": name, "constraint": wanted[name], + "upgradable": upgradable, "latest": latest}) + return rows, out + + +def resolved_versions(pkg_dir, names): + """{name: version} from pubspec.lock for the given names.""" + lock, _ = load_yaml(os.path.join(pkg_dir, "pubspec.lock")) + pkgs = (lock or {}).get("packages") or {} if isinstance(lock, dict) else {} + return {n: (pkgs.get(n) or {}).get("version") for n in names if n in pkgs} + + +def checks(pkg_dir, steps): + """analyze + test for the package, then resolve + analyze its example. + + Mirrors the CI `package` job so a red here means what a red there means. + Appends to `steps`; returns False at the first failure. + """ + plan = [("dart analyze lib", ["dart", "analyze", "lib"], pkg_dir)] + test_dir = os.path.join(pkg_dir, "test") + if os.path.isdir(test_dir): + plan.append(("dart analyze test", ["dart", "analyze", "test"], pkg_dir)) + has_tests = any(f.endswith("_test.dart") + for _, _, files in os.walk(test_dir) for f in files) + if has_tests: + plan.append(("flutter test", ["flutter", "test"], pkg_dir)) + for name, cmd, cwd in plan: + ok, out = run(cmd, cwd) + steps.append({"name": name, "ok": ok, "log": tail(out)}) + if not ok: + return False + return True + + +def example_checks(example_dir, steps, major): + """Resolve the example — against the newest upstream majors when `major`. + + The example is the only place the app-facing upstream package appears + (url_launcher, firebase_auth, ...). Upgrading it across majors is how a + new app-facing major whose platform-interface requirement we exclude shows + up: the resolve fails even though the plugin itself analyses clean. + """ + if not os.path.isfile(os.path.join(example_dir, "pubspec.yaml")): + return True + deps = sorted(hosted_deps(os.path.join(example_dir, "pubspec.yaml"))) + cmd = ["flutter", "pub", "upgrade"] + if major and deps: + cmd += ["--major-versions", *deps] + ok, out = run(cmd, example_dir) + steps.append({"name": "example: " + " ".join(cmd[1:]), "ok": ok, + "log": tail(out)}) + if not ok: + return False + if not os.path.isdir(os.path.join(example_dir, "lib")): + return True + ok, out = run(["dart", "analyze", "lib"], example_dir) + steps.append({"name": "example: dart analyze lib", "ok": ok, "log": tail(out)}) + return ok + + +def same_line(resolved, latest): + """True when `resolved` is on `latest`'s caret line (^latest would allow + it): same major, or same minor below 1.0.0.""" + def parts(v): + try: + return [int(x) for x in re.split(r"[.+-]", v)[:3]] + except (ValueError, TypeError): + return None + a, b = parts(resolved), parts(latest) + if not a or not b: + return resolved == latest + return a[:2] == b[:2] if b[0] == 0 else a[0] == b[0] + + +def force_newest(pkg_dir, rows, steps): + """Make sure the major leg really tests the new majors. + + `pub upgrade --major-versions` is best-effort: when another constraint + holds a dependency back, it keeps the old major and says only "No changes + to pubspec.yaml!" — and the leg would then pass having tested nothing new. + Measured on firebase_auth_tvos: firebase_auth stayed on 6.x because the + sibling firebase_core_tvos pins firebase_core to the previous major. So for + every dependency that did not reach its newest line, ask for it outright + with `pub add name:^latest`. Either that resolves and the checks below run + against it, or it fails with pub's own explanation of what blocks it, + which is the finding. + """ + resolved = resolved_versions(pkg_dir, [r["package"] for r in rows]) + for row in rows: + have = resolved.get(row["package"]) + if have and same_line(have, row["latest"]): + continue + spec = f"{row['package']}:^{row['latest']}" + ok, out = run(["flutter", "pub", "add", spec], pkg_dir) + # The held-back version goes in the log, not the name: the name feeds + # the issue fingerprint, and every upstream patch would rewrite it. + steps.append({"name": f"pub add {spec}", "ok": ok, + "log": f"[pub upgrade --major-versions kept {have}]\n" + tail(out)}) + if not ok: + return False + return True + + +def leg(repo, package, major, rows=()): + """Run one leg on a fresh scratch copy. Returns the leg's report.""" + scratch = tempfile.mkdtemp(prefix=f"upstream-{package}-") + try: + shutil.copytree(os.path.join(repo, "packages"), + os.path.join(scratch, "packages"), ignore=COPY_IGNORE) + pkg_dir = os.path.join(scratch, "packages", package) + pubspec = os.path.join(pkg_dir, "pubspec.yaml") + before = hosted_deps(pubspec) + steps = [] + cmd = ["flutter", "pub", "upgrade"] + if major and before: + # Named deps only: a bare --major-versions would also cross-major + # dev_dependencies such as flutter_lints, and a new lint set is not + # an upstream compatibility problem. + cmd += ["--major-versions", *sorted(before)] + ok, out = run(cmd, pkg_dir) + steps.append({"name": " ".join(cmd[1:]), "ok": ok, "log": tail(out)}) + if ok and major: + ok = force_newest(pkg_dir, rows, steps) + after = hosted_deps(pubspec) + changes = {n: {"from": before[n], "to": after.get(n)} + for n in before if after.get(n) != before[n]} + passed = ok and checks(pkg_dir, steps) and \ + example_checks(os.path.join(pkg_dir, "example"), steps, major) + return { + "passed": passed, + "constraint_changes": changes, + "resolved": resolved_versions(pkg_dir, before), + "steps": steps, + } + finally: + shutil.rmtree(scratch, ignore_errors=True) + + +def tool_versions(): + ok, out = run(["flutter", "--version", "--machine"], ".") + if not ok: + return {} + try: + data = json.loads(out[out.find("{"):]) + except (ValueError, json.JSONDecodeError): + return {} + return {"flutter": data.get("frameworkVersion"), + "dart": data.get("dartSdkVersion")} + + +def fingerprint(report): + """What has to change before an open issue is worth touching again. + + Deliberately excludes logs, which carry timings and paths, and the Flutter + version — every new stable would otherwise rewrite every open issue even + when the failure is the same. A new stable that *changes* the outcome + changes the failing step, which is in here. + """ + def failing(leg_report): + if not leg_report: + return None + return next((s["name"] for s in leg_report["steps"] if not s["ok"]), None) + + key = { + "status": report["status"], + "outdated": sorted((o["package"], o["latest"]) for o in report["outdated"]), + "current": failing(report["legs"].get("current")), + "major": failing(report["legs"].get("major")), + } + blob = json.dumps(key, sort_keys=True).encode() + return hashlib.sha256(blob).hexdigest()[:16] + + +def main(): + parser = argparse.ArgumentParser(description=__doc__.split("\n")[0]) + parser.add_argument("root") + parser.add_argument("package") + parser.add_argument("--out", required=True) + opts = parser.parse_args() + repo = os.path.abspath(opts.root) + pkg_dir = os.path.join(repo, "packages", opts.package) + if not os.path.isfile(os.path.join(pkg_dir, "pubspec.yaml")): + print(f"error: {pkg_dir}/pubspec.yaml not found", file=sys.stderr) + return 2 + + # `pub outdated` needs a resolution; do it on scratch too, so the checkout + # is left exactly as found. + scratch = tempfile.mkdtemp(prefix=f"outdated-{opts.package}-") + try: + shutil.copytree(os.path.join(repo, "packages"), + os.path.join(scratch, "packages"), ignore=COPY_IGNORE) + sdir = os.path.join(scratch, "packages", opts.package) + ok, out = run(["flutter", "pub", "get"], sdir) + rows, out2 = outdated(sdir) if ok else (None, out) + finally: + shutil.rmtree(scratch, ignore_errors=True) + + legs = {"current": leg(repo, opts.package, major=False)} + if rows is None: + # Could not even resolve within the constraints. That is a real + # finding (e.g. a new Flutter whose SDK constraint excludes us) as long + # as the current leg failed the same way; if the current leg passed, + # this was flakiness and no report is trustworthy. + if legs["current"]["passed"]: + print("error: pub outdated failed but the current leg passed:\n" + + tail(out2), file=sys.stderr) + return 3 + rows = [] + if rows: + legs["major"] = leg(repo, opts.package, major=True, rows=rows) + + if not legs["current"]["passed"]: + status = "broken" + elif rows and not legs["major"]["passed"]: + status = "major-breaks" + elif rows: + status = "lag" + else: + status = "ok" + + report = { + "package": opts.package, + "status": status, + "tools": tool_versions(), + "outdated": rows, + "legs": legs, + "run_url": os.environ.get("RUN_URL"), + } + report["fingerprint"] = fingerprint(report) + os.makedirs(opts.out, exist_ok=True) + with open(os.path.join(opts.out, f"{opts.package}.json"), "w", + encoding="utf-8") as handle: + json.dump(report, handle, indent=2) + print(f"{opts.package}: {status} (fingerprint {report['fingerprint']})") + for name, rep in legs.items(): + for step in rep["steps"]: + print(f" [{name}] {'ok ' if step['ok'] else 'FAIL'} {step['name']}") + return 0 + + +if __name__ == "__main__": + sys.exit(main()) diff --git a/.github/scripts/upstream_issues.py b/.github/scripts/upstream_issues.py new file mode 100644 index 0000000..6de0a45 --- /dev/null +++ b/.github/scripts/upstream_issues.py @@ -0,0 +1,206 @@ +#!/usr/bin/env python3 +"""Turn upstream_check.py reports into one GitHub issue per package. + +One issue per package, found by its exact title among issues carrying the +`upstream-compat` label. The body ends in a hidden fingerprint +(see upstream_check.fingerprint), and that is what keeps a daily schedule from +becoming daily noise: + + finding, no open issue open one + finding, open issue, same print leave it alone — no edit, no comment + finding, open issue, new print rewrite the body, add a one-line comment + finding, closed issue, same print + leave it closed: a maintainer closed it + knowing about exactly this finding + ok, open issue comment that it passes again, close it + +A finding that changes after a maintainer closed the issue (a newer upstream +major, a different failing step) opens a fresh issue, because the closing +decision was about something else. + +Usage: + upstream_issues.py --repo owner/name [--dry-run] + +Needs `gh` authenticated with issues: write (GH_TOKEN in Actions). +""" + +import argparse +import glob +import json +import re +import subprocess +import sys + +LABEL = "upstream-compat" +LABEL_COLOR = "fbca04" +LABEL_DESC = "A newer upstream package or Flutter stable breaks or excludes a plugin" +MARKER = re.compile(r"") +BODY_LIMIT = 60000 # GitHub rejects issue bodies over 65536 characters. + +HEADLINES = { + "broken": "fails **within its current constraints** — users are affected now", + "major-breaks": "is excluded by a new upstream major, and moving to it **fails**", + "lag": "is excluded by a new upstream major; moving to it **passes**, so " + "widening the constraint is the fix", +} + + +def title_for(package): + return f"Upstream compatibility: {package}" + + +def gh(args, input_text=None): + """Run gh. Callers guard every write with `dry_run`; only reads get here + unguarded.""" + proc = subprocess.run(["gh", *args], input=input_text, text=True, + stdout=subprocess.PIPE, stderr=subprocess.PIPE) + if proc.returncode != 0: + raise RuntimeError(f"gh {' '.join(args)} failed: {proc.stderr.strip()}") + return proc.stdout + + +def fence(text): + return "```text\n" + text.replace("```", "``​`") + "\n```" + + +def render(report): + pkg = report["package"] + tools = report.get("tools") or {} + out = [f"`{pkg}` {HEADLINES[report['status']]}.", ""] + out.append(f"- Flutter {tools.get('flutter', '?')} (stable), " + f"Dart {tools.get('dart', '?')}") + if report.get("run_url"): + out.append(f"- Run: {report['run_url']}") + out.append("") + + if report["outdated"]: + out += ["### Upstream releases outside our constraints", "", + "| dependency | our constraint | newest allowed | newest release |", + "|---|---|---|---|"] + for o in report["outdated"]: + out.append(f"| `{o['package']}` | `{o['constraint']}` | " + f"{o['upgradable'] or '—'} | **{o['latest']}** |") + out.append("") + + names = {"current": "Within current constraints (`flutter pub upgrade`)", + "major": "Across majors (`flutter pub upgrade --major-versions`)"} + for key in ("current", "major"): + leg = report["legs"].get(key) + if not leg: + continue + verdict = "passes" if leg["passed"] else "**fails**" + out += [f"### {names[key]} — {verdict}", ""] + if leg.get("constraint_changes"): + out.append("Constraint changes pub chose:") + out.append("") + for name, ch in leg["constraint_changes"].items(): + out.append(f"- `{name}`: `{ch['from']}` → `{ch['to']}`") + out.append("") + if leg.get("resolved"): + resolved = ", ".join(f"`{k}` {v}" for k, v in sorted(leg["resolved"].items())) + out += [f"Resolved: {resolved}", ""] + for step in leg["steps"]: + out.append(f"- {'✅' if step['ok'] else '❌'} `{step['name']}`") + failed = next((s for s in leg["steps"] if not s["ok"]), None) + if failed: + out += ["", "
Output of the failing step", + "", fence(failed["log"]), "", "
"] + out.append("") + + out += ["---", + "Filed by the scheduled **Upstream compatibility** workflow. It " + "updates this issue only when the finding changes, and closes it " + "once the package passes again. Closing it by hand silences this " + "exact finding; a different one opens a new issue.", + f""] + body = "\n".join(out) + if len(body) > BODY_LIMIT: + body = body[:BODY_LIMIT] + "\n\n[truncated — see the run log]\n" + out[-1] + return body + + +def existing(repo, package): + """(open_issue, newest_closed_issue) with this package's exact title.""" + raw = gh(["issue", "list", "--repo", repo, "--label", LABEL, "--state", "all", + "--limit", "500", "--json", "number,title,state,body,closedAt"]) + issues = [i for i in json.loads(raw or "[]") if i["title"] == title_for(package)] + open_ = next((i for i in issues if i["state"] == "OPEN"), None) + closed = sorted((i for i in issues if i["state"] != "OPEN"), + key=lambda i: i.get("closedAt") or "", reverse=True) + return open_, (closed[0] if closed else None) + + +def print_of(issue): + match = MARKER.search((issue or {}).get("body") or "") + return match.group(1) if match else None + + +def sync(repo, report, dry_run): + pkg, status = report["package"], report["status"] + open_, closed = existing(repo, pkg) + if status == "ok": + if open_: + print(f"{pkg}: passing again — closing #{open_['number']}") + if not dry_run: + gh(["issue", "close", str(open_["number"]), "--repo", repo, + "--comment", "Passes again against the newest upstream " + f"releases and Flutter stable ({report.get('run_url') or 'scheduled run'}). " + "Closing."]) + else: + print(f"{pkg}: ok") + return + body = render(report) + fp = report["fingerprint"] + if open_: + if print_of(open_) == fp: + print(f"{pkg}: {status}, unchanged — #{open_['number']} left alone") + return + print(f"{pkg}: {status}, finding changed — updating #{open_['number']}") + if not dry_run: + gh(["issue", "edit", str(open_["number"]), "--repo", repo, + "--body-file", "-"], input_text=body) + gh(["issue", "comment", str(open_["number"]), "--repo", repo, "--body", + f"Finding changed (now `{status}`); the description is updated."]) + return + if closed and print_of(closed) == fp: + print(f"{pkg}: {status}, same finding as closed #{closed['number']} — not reopening") + return + print(f"{pkg}: {status} — opening an issue") + if dry_run: + print(body) + return + gh(["issue", "create", "--repo", repo, "--title", title_for(pkg), + "--label", LABEL, "--body-file", "-"], input_text=body) + + +def main(): + parser = argparse.ArgumentParser(description=__doc__.split("\n")[0]) + parser.add_argument("reports") + parser.add_argument("--repo", required=True) + parser.add_argument("--dry-run", action="store_true", + help="read issues, print what would change, write nothing") + opts = parser.parse_args() + + paths = sorted(glob.glob(f"{opts.reports}/**/*.json", recursive=True)) + if not paths: + print("error: no reports found — refusing to treat that as all-clear", + file=sys.stderr) + return 1 + if not opts.dry_run: + gh(["label", "create", LABEL, "--repo", opts.repo, "--color", LABEL_COLOR, + "--description", LABEL_DESC, "--force"]) + errors = 0 + for path in paths: + with open(path, encoding="utf-8") as handle: + report = json.load(handle) + try: + sync(opts.repo, report, opts.dry_run) + except RuntimeError as exc: + # Keep going: one package's API hiccup must not stop the rest. + print(f"error: {report['package']}: {exc}", file=sys.stderr) + errors += 1 + return 1 if errors else 0 + + +if __name__ == "__main__": + sys.exit(main()) diff --git a/.github/workflows/publish.yml b/.github/workflows/publish.yml new file mode 100644 index 0000000..5715253 --- /dev/null +++ b/.github/workflows/publish.yml @@ -0,0 +1,84 @@ +name: Publish + +# Publishes one package to pub.dev from a `-v` tag, using +# pub.dev automated publishing (GitHub OIDC — no stored credentials). +# +# Normally dispatched by release.yml on the tag it just created. Pushing such a +# tag by hand also works. Either way pub.dev itself checks that the event came +# from this repository, from a tag matching the package's configured pattern +# `-v{{version}}`, and from the `pub.dev` environment. +# +# The `resolve` job is a guard, not the security boundary: it refuses a tag +# whose name does not agree with the package's pubspec and changelog, so a +# mistyped tag fails here with a sentence instead of at pub.dev with a 403. + +on: + push: + tags: + - "*_tvos-v[0-9]+.[0-9]+.[0-9]+*" + workflow_dispatch: + +permissions: + contents: read + +concurrency: + group: publish-${{ github.ref }} + cancel-in-progress: false + +jobs: + resolve: + runs-on: ubuntu-latest + outputs: + package: ${{ steps.parse.outputs.package }} + version: ${{ steps.parse.outputs.version }} + steps: + - uses: actions/checkout@v4 + - name: Ensure PyYAML + run: python3 -c "import yaml" 2>/dev/null || pip install --quiet pyyaml + - id: parse + env: + REF_TYPE: ${{ github.ref_type }} + TAG: ${{ github.ref_name }} + run: | + set -euo pipefail + if [ "$REF_TYPE" != tag ]; then + echo "::error::Publish must run on a tag ref (got $REF_TYPE '$TAG'). Dispatch it with --ref -v." + exit 1 + fi + python3 - <<'PY' + import os, re, sys + sys.path.insert(0, ".github/scripts") + from check_repo import load_yaml, newest_changelog_version, read_text + tag = os.environ["TAG"] + m = re.fullmatch(r"([a-z0-9_]+)-v(.+)", tag) + if not m: + sys.exit(f"::error::Tag '{tag}' is not -v.") + pkg, version = m.groups() + d = os.path.join("packages", pkg) + pubspec, err = load_yaml(os.path.join(d, "pubspec.yaml")) + if err or not isinstance(pubspec, dict): + sys.exit(f"::error::No readable packages/{pkg}/pubspec.yaml ({err}).") + if pubspec.get("version") != version: + sys.exit(f"::error::Tag says {version}, pubspec.yaml says {pubspec.get('version')}.") + text, _ = read_text(os.path.join(d, "CHANGELOG.md")) + top, heading = newest_changelog_version(text or "") + if top != version: + sys.exit(f"::error::Newest CHANGELOG heading is '{heading}', not {version}.") + with open(os.environ["GITHUB_OUTPUT"], "a") as fh: + fh.write(f"package={pkg}\nversion={version}\n") + print(f"Publishing {pkg} {version}") + PY + + publish: + name: ${{ needs.resolve.outputs.package }} ${{ needs.resolve.outputs.version }} + needs: resolve + permissions: + id-token: write # OIDC token for pub.dev + # dart-lang's reusable workflow: validates, builds the archive in a job + # without network access, then uploads it from a job in `environment`. + # use-flutter defaults to true, which these Flutter plugins need for + # `pub get`. + uses: dart-lang/setup-dart/.github/workflows/publish.yml@v1 + with: + environment: pub.dev + working-directory: packages/${{ needs.resolve.outputs.package }} diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml new file mode 100644 index 0000000..97f7c1c --- /dev/null +++ b/.github/workflows/release.yml @@ -0,0 +1,166 @@ +name: Release + +# Merge to main → CI green → tag → publish to pub.dev. +# +# Runs after CI finishes on a push to main, and only if it succeeded, so a +# release never goes out from a commit CI rejected. release_plan.py picks the +# packages whose pubspec version is not on pub.dev yet (and checks that the +# version tops CHANGELOG.md and is newer than what pub.dev has). Each candidate +# is re-verified on exactly that commit — analyse, test, `flutter pub publish +# --dry-run` — then tagged `-v`, and publish.yml is +# dispatched on the tag. +# +# Why dispatch instead of letting the tag push trigger publish.yml: a tag +# created with GITHUB_TOKEN does not trigger `on: push` workflows (GitHub's +# guard against recursive runs), but a workflow_dispatch from GITHUB_TOKEN is +# allowed. pub.dev accepts both events from a tag ref once each package has +# "workflow_dispatch" enabled in its automated-publishing settings. No PAT or +# app token is needed. Pushing a tag by hand still works through `on: push`. +# +# workflow_dispatch here re-runs the plan on the tip of main — the way to +# retry after fixing pub.dev settings, or when back-to-back merges made CI +# skip a commit (see the concurrency note in ci.yml). + +on: + workflow_run: + workflows: [CI] + types: [completed] + branches: [main] + workflow_dispatch: + +permissions: + contents: read + +concurrency: + # Never cancel: a half-finished release (tagged, not dispatched) is the one + # state this workflow should not leave behind. + group: release + cancel-in-progress: false + +jobs: + plan: + if: >- + github.event_name == 'workflow_dispatch' || + (github.event.workflow_run.conclusion == 'success' && + github.event.workflow_run.event == 'push') + runs-on: ubuntu-latest + outputs: + sha: ${{ steps.sha.outputs.sha }} + candidates: ${{ steps.plan.outputs.candidates }} + problems: ${{ steps.plan.outputs.problems }} + flutter: ${{ steps.flutter.outputs.version }} + steps: + - id: sha + run: echo "sha=${{ github.event.workflow_run.head_sha || github.sha }}" >> "$GITHUB_OUTPUT" + + - uses: actions/checkout@v4 + with: + ref: ${{ steps.sha.outputs.sha }} + + # Only ever release what main points at. A workflow_run for an older + # commit can arrive after a newer one has landed; its packages will be + # picked up by the newer commit's own run. + - name: Commit is still on main + if: github.event_name == 'workflow_run' + run: | + git fetch --depth=1 origin main + if [ "$(git rev-parse FETCH_HEAD)" != "${{ steps.sha.outputs.sha }}" ]; then + echo "::notice::main has moved past ${{ steps.sha.outputs.sha }}; the newer run releases." + echo "SKIP=1" >> "$GITHUB_ENV" + fi + + # One source of truth for the Flutter version: the one CI just passed with. + - id: flutter + run: | + v=$(sed -n 's/^ FLUTTER_VERSION: *"\(.*\)".*/\1/p' .github/workflows/ci.yml) + [ -n "$v" ] || { echo "::error::FLUTTER_VERSION not found in ci.yml"; exit 1; } + echo "version=$v" >> "$GITHUB_OUTPUT" + + - name: Ensure PyYAML + run: python3 -c "import yaml" 2>/dev/null || pip install --quiet pyyaml + + - id: plan + run: | + if [ "${SKIP:-}" = 1 ]; then + echo "candidates=[]" >> "$GITHUB_OUTPUT" + echo "problems=0" >> "$GITHUB_OUTPUT" + exit 0 + fi + python3 .github/scripts/release_plan.py . --github-output + + release: + name: ${{ matrix.package }} ${{ matrix.version }} + needs: plan + if: needs.plan.outputs.candidates != '[]' && needs.plan.outputs.candidates != '' + runs-on: ubuntu-latest + permissions: + contents: write # create the tag + actions: write # dispatch publish.yml + strategy: + fail-fast: false + matrix: + include: ${{ fromJSON(needs.plan.outputs.candidates) }} + defaults: + run: + working-directory: packages/${{ matrix.package }} + steps: + - uses: actions/checkout@v4 + with: + ref: ${{ needs.plan.outputs.sha }} + + - uses: subosito/flutter-action@v2 + with: + flutter-version: ${{ needs.plan.outputs.flutter }} + channel: stable + cache: true + + - run: flutter pub get + + # Same checks as CI's package job. CI already passed on this commit; + # repeating the package's own half costs a minute and means the tag is + # placed by a job that saw the checks pass, not one that trusted a status. + - name: dart analyze + run: | + dart analyze lib + if [ -d test ]; then dart analyze test; fi + + - name: flutter test + run: | + if find test -name '*_test.dart' -print -quit 2>/dev/null | grep -q .; then + flutter test + else + echo "::warning::no tests to run" + fi + + # Exits non-zero on warnings; hints (such as the pubspec_overrides one + # the firebase packages get) do not fail it. + - name: flutter pub publish --dry-run + run: flutter pub publish --dry-run + + - name: Tag ${{ matrix.tag }} + if: ${{ !matrix.tag_exists }} + env: + GH_TOKEN: ${{ github.token }} + run: | + gh api "repos/${{ github.repository }}/git/refs" \ + -f ref="refs/tags/${{ matrix.tag }}" \ + -f sha="${{ needs.plan.outputs.sha }}" + + - name: Dispatch publish on ${{ matrix.tag }} + env: + GH_TOKEN: ${{ github.token }} + run: | + gh workflow run publish.yml --repo "${{ github.repository }}" --ref "${{ matrix.tag }}" + echo "Publishing ${{ matrix.package }} ${{ matrix.version }} — follow it under the Publish workflow." >> "$GITHUB_STEP_SUMMARY" + + # Packages whose metadata release_plan.py rejected (version not on top of + # CHANGELOG.md, not newer than pub.dev, ...). Kept out of `plan` so the + # healthy packages in the same merge still release, but the run ends red. + problems: + needs: [plan, release] + if: ${{ !cancelled() && needs.plan.result == 'success' && needs.plan.outputs.problems != '0' }} + runs-on: ubuntu-latest + steps: + - run: | + echo "::error::${{ needs.plan.outputs.problems }} package(s) were not released; see the plan job's errors." + exit 1 diff --git a/.github/workflows/upstream-compat.yml b/.github/workflows/upstream-compat.yml new file mode 100644 index 0000000..aaf55cc --- /dev/null +++ b/.github/workflows/upstream-compat.yml @@ -0,0 +1,148 @@ +name: Upstream compatibility + +# Catches upstream releases that break or exclude a plugin with no commit here: +# a new upstream major outside our constraint, a minor release of a platform +# interface that adds an abstract member, a new Flutter stable that rejects our +# code. CI cannot see any of these — it is pinned on purpose, and runs only when +# something here changes. +# +# Per package, upstream_check.py runs two legs on scratch copies of packages/: +# current `flutter pub upgrade` (newest within our constraints) +# major `flutter pub upgrade --major-versions ` — run +# only when pub outdated says a newer major exists +# each followed by the CI package job's checks (analyse lib + test, flutter +# test, resolve + analyse the example). upstream_issues.py then keeps exactly +# one issue per package under the `upstream-compat` label, touching it only +# when the finding changes, and closing it when the package passes again. +# +# Flutter is NOT pinned here, unlike CI: tracking the newest stable is the +# point. If CI is green and this goes red on `current`, compare the Flutter +# version in the issue with FLUTTER_VERSION in ci.yml first. +# +# Same blind spot as CI: nothing tvOS-native is compiled. An upstream change +# that only shows up in Swift/ObjC is invisible here. + +on: + schedule: + - cron: "17 5 * * *" # daily, off the hour to dodge the scheduler rush + workflow_dispatch: + inputs: + package: + description: "Only this package (blank = all)" + required: false + default: "" + flutter_version: + description: "Flutter version (blank = newest stable)" + required: false + default: "" + dry_run: + description: "Report only; do not open, edit or close issues" + type: boolean + default: false + +permissions: + contents: read + +concurrency: + group: ${{ github.workflow }} + cancel-in-progress: false + +jobs: + list: + runs-on: ubuntu-latest + outputs: + packages: ${{ steps.list.outputs.packages }} + steps: + - uses: actions/checkout@v4 + - name: Ensure PyYAML + run: python3 -c "import yaml" 2>/dev/null || pip install --quiet pyyaml + - id: list + env: + ONLY: ${{ inputs.package }} + run: | + set -euo pipefail + names=$(python3 .github/scripts/check_repo.py --list .) + if [ -n "${ONLY:-}" ]; then + if ! printf '%s\n' "$names" | grep -qx -- "$ONLY"; then + echo "::error::No package named '$ONLY' under packages/." + exit 1 + fi + names=$ONLY + fi + pkgs=$(printf '%s\n' "$names" | jq -R -s -c 'split("\n") | map(select(length > 0))') + case "$pkgs" in + \[\]) echo "::error::No packages discovered."; exit 1 ;; + \[*\]) ;; + *) echo "::error::Package list is not a JSON array: '$pkgs'"; exit 1 ;; + esac + echo "packages=$pkgs" >> "$GITHUB_OUTPUT" + + check: + name: ${{ matrix.package }} + needs: list + runs-on: ubuntu-latest + timeout-minutes: 45 + strategy: + fail-fast: false + matrix: + package: ${{ fromJSON(needs.list.outputs.packages) }} + steps: + - uses: actions/checkout@v4 + + - uses: subosito/flutter-action@v2 + with: + channel: stable + flutter-version: ${{ inputs.flutter_version }} + cache: true + + - name: Ensure PyYAML + run: python3 -c "import yaml" 2>/dev/null || pip install --quiet pyyaml + + # Exits 0 whenever it wrote a report, broken package included. A non-zero + # exit means the tooling itself failed, and this leg goes red without a + # report — so no issue gets filed about a network blip. + - name: Check against newest upstream + env: + RUN_URL: ${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }} + run: python3 .github/scripts/upstream_check.py . "${{ matrix.package }}" --out reports + + - uses: actions/upload-artifact@v4 + with: + name: upstream-${{ matrix.package }} + path: reports/ + if-no-files-found: error + retention-days: 14 + + issues: + # `!cancelled()`: a red leg (tooling failure) must not stop the other + # packages' findings from being filed. A package without a report is + # simply absent; its open issue, if any, is left as it was. + if: ${{ !cancelled() }} + needs: check + runs-on: ubuntu-latest + permissions: + contents: read + issues: write + steps: + - uses: actions/checkout@v4 + - uses: actions/download-artifact@v4 + with: + pattern: upstream-* + path: reports + - name: Sync issues + env: + GH_TOKEN: ${{ github.token }} + DRY_RUN: ${{ inputs.dry_run && '--dry-run' || '' }} + run: | + set -euo pipefail + # shellcheck disable=SC2086 # DRY_RUN is empty or one flag + python3 .github/scripts/upstream_issues.py reports --repo "${{ github.repository }}" $DRY_RUN + - name: Summary + run: | + { + echo "| package | status |" + echo "|---|---|" + for f in reports/*/*.json; do + jq -r '"| \(.package) | \(.status) |"' "$f" + done + } >> "$GITHUB_STEP_SUMMARY" diff --git a/.gitignore b/.gitignore index 8c2fb57..1ba2633 100644 --- a/.gitignore +++ b/.gitignore @@ -40,3 +40,6 @@ pubspec.lock *.iml .vscode/ .DS_Store + +# Python +__pycache__/ diff --git a/AUTHORING.md b/AUTHORING.md index 8e4c8c0..51dacaf 100644 --- a/AUTHORING.md +++ b/AUTHORING.md @@ -252,6 +252,32 @@ git push Make sure your git identity is set to your personal profile, not a CI bot. CI will run `flutter pub get` + `flutter analyze` on the new package. +## 7. Releasing + +Releases go out from `main` on their own. To release a package, bump +`version:` in its `pubspec.yaml` (and `s.version` in the podspec) and add a +matching `## ` heading at the top of `CHANGELOG.md`, in the same PR. +After the merge, once CI is green on `main`, the **Release** workflow +re-checks the package, tags the commit `-v` and dispatches +**Publish**, which uploads to pub.dev through automated publishing (GitHub +OIDC; nothing to store as a secret). + +- A version already on pub.dev is skipped, so packages you didn't bump are + left alone. +- A version that doesn't top `CHANGELOG.md`, or isn't newer than what pub.dev + has, fails the Release run and isn't published. +- A brand-new package can't be published automatically. Publish its first + version by hand with `flutter pub publish`, then enable automated publishing + for it on pub.dev (tag pattern `-v{{version}}`, `push` and + `workflow_dispatch` events, environment `pub.dev`). +- To retry a failed publish, run **Release** from the Actions tab. It + re-dispatches publishing for any tagged version that pub.dev doesn't have yet. + +The **Upstream compatibility** workflow runs daily. It tests every package +against the newest upstream releases and the newest Flutter stable, and keeps +one `upstream-compat` issue per package that is broken or held back by its +constraints. That issue is closed automatically once the package passes again. + --- ## Checklist (use this when porting) From c8eb393b244dfc1b26ae8232d71e4886001b7cf3 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Mehmet=20Ali=20Ustao=C4=9Flu?= Date: Sun, 8 Nov 2026 23:02:50 +0100 Subject: [PATCH 2/3] ci: fix review findings in upstream-compat and release Upstream compatibility: - An issue the workflow closed itself (package passing again) is marked auto-closed and never silences a later identical finding; only a hand-closed issue does. A hand-reopened auto-closed issue loses the marker. - Fingerprints and step names count upstream releases by caret line, so an upstream patch or minor no longer edits open issues or reopens hand-closed ones; a new major still does. - A resolve step that fails with pub's network errors makes the check exit 4 with no report instead of filing a `broken` issue. - outdated rows need a newer caret line, not just any newer release. Release and publish: - Release dispatched by hand only runs on main. - An existing tag is re-dispatched only when it points at the verified commit and no Publish run for it is still active; a tag on an older commit fails the run. - Publish refuses a tag whose commit is not on main. - release_plan orders build metadata as pub does and reports tag SHAs (peeled for annotated tags). - Corrected the description of dart-lang's reusable publish workflow. --- .github/scripts/release_plan.py | 50 ++++++++++------ .github/scripts/upstream_check.py | 95 ++++++++++++++++++++++++------ .github/scripts/upstream_issues.py | 32 ++++++++-- .github/workflows/publish.yml | 24 ++++++-- .github/workflows/release.yml | 52 ++++++++++++++-- AUTHORING.md | 8 ++- 6 files changed, 210 insertions(+), 51 deletions(-) diff --git a/.github/scripts/release_plan.py b/.github/scripts/release_plan.py index ab22db0..0194a36 100644 --- a/.github/scripts/release_plan.py +++ b/.github/scripts/release_plan.py @@ -18,10 +18,12 @@ only allows automated publishing for packages that already exist, so the first version has to go up with `flutter pub publish` by hand. -Output: a JSON list on stdout, one {package, version, tag, tag_exists} per -candidate. `tag_exists` means an earlier run tagged this version but pub.dev -still does not have it — the publish failed or was never approved — and the -release job re-dispatches publishing instead of tagging again. +Output: a JSON list on stdout, one {package, version, tag, tag_exists, +tag_sha} per candidate. `tag_exists` means an earlier run tagged this version +but pub.dev still does not have it — the publish failed, is still running, or +is waiting for approval. The release job then re-dispatches publishing instead +of tagging again, but only when `tag_sha` is the commit it just verified and no +Publish run for the tag is already active. Exits non-zero if any package's metadata is inconsistent, so a bad bump fails the run in plain sight rather than quietly not publishing. With @@ -47,7 +49,7 @@ discover, load_yaml, newest_changelog_version, read_text, ) -SEMVER = re.compile(r"^(\d+)\.(\d+)\.(\d+)(?:-([0-9A-Za-z.-]+))?(?:\+[0-9A-Za-z.-]+)?$") +SEMVER = re.compile(r"^(\d+)\.(\d+)\.(\d+)(?:-([0-9A-Za-z.-]+))?(?:\+([0-9A-Za-z.-]+))?$") def tag_for(package, version): @@ -56,15 +58,20 @@ def tag_for(package, version): def semver_key(version): - """Sort key with semver precedence: a prerelease sorts below its release.""" + """Sort key with pub's precedence: a prerelease sorts below its release, + and, unlike strict semver, build metadata counts — 1.0.0+2 is newer than + 1.0.0+1, which is newer than 1.0.0.""" m = SEMVER.match(version) if not m: return None - major, minor, patch, pre = m.groups() - pre_key = (1,) if pre is None else (0, *[ - (0, int(p), "") if p.isdigit() else (1, 0, p) for p in pre.split(".") - ]) - return (int(major), int(minor), int(patch), pre_key) + major, minor, patch, pre, build = m.groups() + + def ids(text): + return [(0, int(p), "") if p.isdigit() else (1, 0, p) + for p in text.split(".")] + pre_key = (1,) if pre is None else (0, *ids(pre)) + build_key = () if build is None else tuple(ids(build)) + return (int(major), int(minor), int(patch), pre_key, build_key) def pub_versions(package): @@ -89,17 +96,23 @@ def pub_versions(package): def remote_tags(root): - """Tag names on origin. ls-remote, not local tags: the checkout is shallow - and may not have fetched them.""" + """{tag name: commit sha} on origin. ls-remote, not local tags: the + checkout is shallow and may not have fetched them. An annotated tag is + listed twice; its peeled `^{}` line is the commit it points at.""" proc = subprocess.run(["git", "ls-remote", "--tags", "origin"], cwd=root, stdout=subprocess.PIPE, stderr=subprocess.PIPE, text=True) if proc.returncode != 0: raise RuntimeError(f"git ls-remote failed: {proc.stderr.strip()}") - tags = set() + tags = {} for line in proc.stdout.splitlines(): - ref = line.split("\t")[-1] - if ref.startswith("refs/tags/"): - tags.add(ref[len("refs/tags/"):].removesuffix("^{}")) + sha, _, ref = line.partition("\t") + if not ref.startswith("refs/tags/"): + continue + name = ref[len("refs/tags/"):] + if name.endswith("^{}"): + tags[name.removesuffix("^{}")] = sha + else: + tags.setdefault(name, sha) return tags @@ -145,7 +158,8 @@ def plan(root, tags): continue tag = tag_for(pkg, version) candidates.append({"package": pkg, "version": version, "tag": tag, - "tag_exists": tag in tags}) + "tag_exists": tag in tags, + "tag_sha": tags.get(tag, "")}) return candidates, problems diff --git a/.github/scripts/upstream_check.py b/.github/scripts/upstream_check.py index 76eb9c2..7809cdc 100644 --- a/.github/scripts/upstream_check.py +++ b/.github/scripts/upstream_check.py @@ -26,7 +26,9 @@ exit code is about the tooling, not the findings: 0 whenever a report was written, including for a broken package, so one package's breakage cannot hide another's. Non-zero means no trustworthy report exists, and the workflow fails -loudly instead of filing an issue about a network blip. +loudly instead of filing an issue about a network blip: a resolve step that +fails with pub's network errors (pub.dev unreachable, socket errors, 5xx) is a +tooling failure, never a finding. Usage: upstream_check.py --out @@ -50,6 +52,22 @@ # Ignored when copying packages/ to scratch: build output and resolution state # that would make a scratch run differ from a fresh checkout. +# pub's own wording when it could not talk to the package server. A resolve +# step that fails with one of these says nothing about our package. +NETWORK_ERROR = re.compile( + r"Got socket error|SocketException|Failed host lookup|HandshakeException|" + r"Connection (?:refused|reset|closed|timed out)|" + r"pub\.dev is having some trouble|having some trouble connecting|" + r"Server error|Could not resolve URL|Network is unreachable|" + r"TimeoutException", + re.IGNORECASE, +) + + +class ToolingError(Exception): + """The run cannot produce a trustworthy report (network, pub.dev down).""" + + COPY_IGNORE = shutil.ignore_patterns( ".dart_tool", "build", "pubspec.lock", ".flutter-plugins", ".flutter-plugins-dependencies", "Pods", ".symlinks", "DerivedData", @@ -73,6 +91,16 @@ def run(cmd, cwd): return False, f"[could not run {cmd[0]}: {exc}]" +def resolve(cmd, cwd): + """run() for a pub command that talks to the package server. A failure + caused by the network raises ToolingError instead of becoming a step.""" + ok, out = run(cmd, cwd) + if not ok and NETWORK_ERROR.search(out): + raise ToolingError(f"{' '.join(cmd)} in {cwd} hit a network error:\n" + + tail(out, 20)) + return ok, out + + def tail(text, n=LOG_TAIL): lines = text.rstrip().splitlines() if len(lines) <= n: @@ -112,11 +140,14 @@ def outdated(pkg_dir): `pub outdated` already knows the difference: `upgradable` is the newest version the current constraints allow, `latest` the newest stable release. - When they differ for a direct dependency, the constraint is what holds us - back. Prereleases are not counted — `latest` excludes them by default. + When they differ by a major (a minor below 1.0.0) for a direct + dependency, a constraint is what holds us back — ours, or a sibling's. + A newer release on the same line that pub could not pick (an SDK bound, a + transitive pin) is the current leg's business, not a new major, so it is + not a row. Prereleases are not counted — `latest` excludes them by default. """ - ok, out = run(["flutter", "pub", "outdated", "--json", - "--no-dev-dependencies"], pkg_dir) + ok, out = resolve(["flutter", "pub", "outdated", "--json", + "--no-dev-dependencies"], pkg_dir) if not ok: return None, out start = out.find("{") @@ -132,7 +163,8 @@ def outdated(pkg_dir): continue upgradable = (row.get("upgradable") or {}).get("version") latest = (row.get("latest") or {}).get("version") - if latest and upgradable != latest: + if latest and upgradable != latest and not ( + upgradable and same_line(upgradable, latest)): rows.append({"package": name, "constraint": wanted[name], "upgradable": upgradable, "latest": latest}) return rows, out @@ -181,7 +213,7 @@ def example_checks(example_dir, steps, major): cmd = ["flutter", "pub", "upgrade"] if major and deps: cmd += ["--major-versions", *deps] - ok, out = run(cmd, example_dir) + ok, out = resolve(cmd, example_dir) steps.append({"name": "example: " + " ".join(cmd[1:]), "ok": ok, "log": tail(out)}) if not ok: @@ -207,6 +239,18 @@ def parts(v): return a[:2] == b[:2] if b[0] == 0 else a[0] == b[0] +def caret_line(version): + """The caret line a version starts: "8" for 8.0.2, "0.5" for 0.5.3. + + Fingerprints and step names use this rather than the full version, so an + upstream patch or minor on the same line does not count as a new finding. + """ + parts = re.split(r"[.+-]", version or "") + if len(parts) >= 2 and parts[0] == "0": + return f"0.{parts[1]}" + return parts[0] if parts and parts[0] else str(version) + + def force_newest(pkg_dir, rows, steps): """Make sure the major leg really tests the new majors. @@ -226,11 +270,14 @@ def force_newest(pkg_dir, rows, steps): if have and same_line(have, row["latest"]): continue spec = f"{row['package']}:^{row['latest']}" - ok, out = run(["flutter", "pub", "add", spec], pkg_dir) - # The held-back version goes in the log, not the name: the name feeds - # the issue fingerprint, and every upstream patch would rewrite it. - steps.append({"name": f"pub add {spec}", "ok": ok, - "log": f"[pub upgrade --major-versions kept {have}]\n" + tail(out)}) + ok, out = resolve(["flutter", "pub", "add", spec], pkg_dir) + # Exact versions go in the log, not the name: the name feeds the issue + # fingerprint, and every upstream patch would otherwise rewrite it. + steps.append({"name": f"pub add {row['package']} " + f"(newest line, {caret_line(row['latest'])}.x)", + "ok": ok, + "log": f"[pub add {spec}; pub upgrade --major-versions " + f"kept {have}]\n" + tail(out)}) if not ok: return False return True @@ -252,7 +299,7 @@ def leg(repo, package, major, rows=()): # dev_dependencies such as flutter_lints, and a new lint set is not # an upstream compatibility problem. cmd += ["--major-versions", *sorted(before)] - ok, out = run(cmd, pkg_dir) + ok, out = resolve(cmd, pkg_dir) steps.append({"name": " ".join(cmd[1:]), "ok": ok, "log": tail(out)}) if ok and major: ok = force_newest(pkg_dir, rows, steps) @@ -286,9 +333,11 @@ def tool_versions(): def fingerprint(report): """What has to change before an open issue is worth touching again. - Deliberately excludes logs, which carry timings and paths, and the Flutter - version — every new stable would otherwise rewrite every open issue even - when the failure is the same. A new stable that *changes* the outcome + Deliberately excludes logs, which carry timings and paths, the Flutter + version, and exact upstream versions — every new stable or upstream patch + would otherwise rewrite every open issue even when the failure is the + same. Upstream releases count by caret line, so a new *major* is a new + finding and 8.0.1 → 8.0.2 is not. A new stable that *changes* the outcome changes the failing step, which is in here. """ def failing(leg_report): @@ -298,7 +347,8 @@ def failing(leg_report): key = { "status": report["status"], - "outdated": sorted((o["package"], o["latest"]) for o in report["outdated"]), + "outdated": sorted((o["package"], caret_line(o["latest"])) + for o in report["outdated"]), "current": failing(report["legs"].get("current")), "major": failing(report["legs"].get("major")), } @@ -318,6 +368,15 @@ def main(): print(f"error: {pkg_dir}/pubspec.yaml not found", file=sys.stderr) return 2 + try: + return check(repo, opts) + except ToolingError as exc: + print(f"error: no trustworthy report for {opts.package}: {exc}", + file=sys.stderr) + return 4 + + +def check(repo, opts): # `pub outdated` needs a resolution; do it on scratch too, so the checkout # is left exactly as found. scratch = tempfile.mkdtemp(prefix=f"outdated-{opts.package}-") @@ -325,7 +384,7 @@ def main(): shutil.copytree(os.path.join(repo, "packages"), os.path.join(scratch, "packages"), ignore=COPY_IGNORE) sdir = os.path.join(scratch, "packages", opts.package) - ok, out = run(["flutter", "pub", "get"], sdir) + ok, out = resolve(["flutter", "pub", "get"], sdir) rows, out2 = outdated(sdir) if ok else (None, out) finally: shutil.rmtree(scratch, ignore_errors=True) diff --git a/.github/scripts/upstream_issues.py b/.github/scripts/upstream_issues.py index 6de0a45..0432bc9 100644 --- a/.github/scripts/upstream_issues.py +++ b/.github/scripts/upstream_issues.py @@ -9,14 +9,18 @@ finding, no open issue open one finding, open issue, same print leave it alone — no edit, no comment finding, open issue, new print rewrite the body, add a one-line comment - finding, closed issue, same print + finding, hand-closed issue, same print leave it closed: a maintainer closed it knowing about exactly this finding - ok, open issue comment that it passes again, close it + ok, open issue mark the body auto-closed, comment that it + passes again, close it A finding that changes after a maintainer closed the issue (a newer upstream major, a different failing step) opens a fresh issue, because the closing -decision was about something else. +decision was about something else. An issue this script closed itself never +silences anything: the same finding coming back later is a new regression, so +it opens a fresh issue. The AUTO_CLOSED marker in the body is how the two kinds +of closed issue are told apart. Usage: upstream_issues.py --repo owner/name [--dry-run] @@ -35,6 +39,7 @@ LABEL_COLOR = "fbca04" LABEL_DESC = "A newer upstream package or Flutter stable breaks or excludes a plugin" MARKER = re.compile(r"") +AUTO_CLOSED = "" BODY_LIMIT = 60000 # GitHub rejects issue bodies over 65536 characters. HEADLINES = { @@ -135,6 +140,10 @@ def print_of(issue): return match.group(1) if match else None +def auto_closed(issue): + return AUTO_CLOSED in ((issue or {}).get("body") or "") + + def sync(repo, report, dry_run): pkg, status = report["package"], report["status"] open_, closed = existing(repo, pkg) @@ -142,6 +151,9 @@ def sync(repo, report, dry_run): if open_: print(f"{pkg}: passing again — closing #{open_['number']}") if not dry_run: + body = (open_.get("body") or "").replace(AUTO_CLOSED, "").rstrip() + gh(["issue", "edit", str(open_["number"]), "--repo", repo, + "--body-file", "-"], input_text=f"{body}\n{AUTO_CLOSED}") gh(["issue", "close", str(open_["number"]), "--repo", repo, "--comment", "Passes again against the newest upstream " f"releases and Flutter stable ({report.get('run_url') or 'scheduled run'}). " @@ -153,6 +165,15 @@ def sync(repo, report, dry_run): fp = report["fingerprint"] if open_: if print_of(open_) == fp: + if auto_closed(open_): + # Reopened by hand after an auto-close: drop the marker so that + # closing it by hand again does silence this finding. + print(f"{pkg}: {status}, unchanged — clearing the auto-closed " + f"marker on reopened #{open_['number']}") + if not dry_run: + gh(["issue", "edit", str(open_["number"]), "--repo", repo, + "--body-file", "-"], input_text=body) + return print(f"{pkg}: {status}, unchanged — #{open_['number']} left alone") return print(f"{pkg}: {status}, finding changed — updating #{open_['number']}") @@ -162,8 +183,9 @@ def sync(repo, report, dry_run): gh(["issue", "comment", str(open_["number"]), "--repo", repo, "--body", f"Finding changed (now `{status}`); the description is updated."]) return - if closed and print_of(closed) == fp: - print(f"{pkg}: {status}, same finding as closed #{closed['number']} — not reopening") + if closed and print_of(closed) == fp and not auto_closed(closed): + print(f"{pkg}: {status}, same finding as hand-closed " + f"#{closed['number']} — not reopening") return print(f"{pkg}: {status} — opening an issue") if dry_run: diff --git a/.github/workflows/publish.yml b/.github/workflows/publish.yml index 5715253..f4c4c34 100644 --- a/.github/workflows/publish.yml +++ b/.github/workflows/publish.yml @@ -11,6 +11,9 @@ name: Publish # The `resolve` job is a guard, not the security boundary: it refuses a tag # whose name does not agree with the package's pubspec and changelog, so a # mistyped tag fails here with a sentence instead of at pub.dev with a 403. +# It also refuses a tag on a commit that is not on main: the tag patterns on +# pub.dev and in the environment limit the tag's *name*, not which commit it +# points at, and only main has been through review and CI. on: push: @@ -35,6 +38,18 @@ jobs: - uses: actions/checkout@v4 - name: Ensure PyYAML run: python3 -c "import yaml" 2>/dev/null || pip install --quiet pyyaml + - name: Tagged commit is on main + env: + GH_TOKEN: ${{ github.token }} + run: | + set -euo pipefail + # identical: main is this commit; behind: main has it as an ancestor. + state=$(gh api "repos/$GITHUB_REPOSITORY/compare/main...$GITHUB_SHA" --jq .status) + case "$state" in + identical|behind) echo "$GITHUB_SHA is on main ($state)." ;; + *) echo "::error::$GITHUB_REF_NAME points at $GITHUB_SHA, which is not on main ($state). Only merged commits are published." + exit 1 ;; + esac - id: parse env: REF_TYPE: ${{ github.ref_type }} @@ -74,10 +89,11 @@ jobs: needs: resolve permissions: id-token: write # OIDC token for pub.dev - # dart-lang's reusable workflow: validates, builds the archive in a job - # without network access, then uploads it from a job in `environment`. - # use-flutter defaults to true, which these Flutter plugins need for - # `pub get`. + # dart-lang's reusable workflow: one job in `environment` that checks out + # the tag, installs Dart and the newest Flutter stable (not CI's pinned + # version; Release's dry-run used the pinned one), then runs `pub get`, + # `pub publish --dry-run` and `pub publish -f` with the OIDC token. Its + # only inputs are `environment` and `working-directory`. uses: dart-lang/setup-dart/.github/workflows/publish.yml@v1 with: environment: pub.dev diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml index 97f7c1c..ca4bdfe 100644 --- a/.github/workflows/release.yml +++ b/.github/workflows/release.yml @@ -19,7 +19,15 @@ name: Release # # workflow_dispatch here re-runs the plan on the tip of main — the way to # retry after fixing pub.dev settings, or when back-to-back merges made CI -# skip a commit (see the concurrency note in ci.yml). +# skip a commit (see the concurrency note in ci.yml). It only runs when +# dispatched on main; any other ref is refused, so an unmerged branch can +# never be tagged. +# +# A tag that already exists is re-dispatched only when it points at the commit +# this run verified and no Publish run for it is still active (running, or +# waiting for approval in the pub.dev environment). A tag on an older commit +# fails the run: publishing it would ship code this run never checked. Bump the +# version, or delete the tag if its publish never happened. on: workflow_run: @@ -40,7 +48,8 @@ concurrency: jobs: plan: if: >- - github.event_name == 'workflow_dispatch' || + (github.event_name == 'workflow_dispatch' && + github.ref == 'refs/heads/main') || (github.event.workflow_run.conclusion == 'success' && github.event.workflow_run.event == 'push') runs-on: ubuntu-latest @@ -60,8 +69,9 @@ jobs: # Only ever release what main points at. A workflow_run for an older # commit can arrive after a newer one has landed; its packages will be # picked up by the newer commit's own run. + # A dispatch is on main already (see the job's `if`); checking it too + # costs nothing and catches a push that landed while it queued. - name: Commit is still on main - if: github.event_name == 'workflow_run' run: | git fetch --depth=1 origin main if [ "$(git rev-parse FETCH_HEAD)" != "${{ steps.sha.outputs.sha }}" ]; then @@ -104,27 +114,59 @@ jobs: run: working-directory: packages/${{ matrix.package }} steps: + # An existing tag: publish only what this run verifies, and never start + # a second Publish for a tag whose first one is still going. + - name: Tag state + id: state + if: ${{ matrix.tag_exists }} + working-directory: . + env: + GH_TOKEN: ${{ github.token }} + TAG: ${{ matrix.tag }} + TAG_SHA: ${{ matrix.tag_sha }} + SHA: ${{ needs.plan.outputs.sha }} + run: | + set -euo pipefail + active=$(gh run list --repo "$GITHUB_REPOSITORY" --workflow publish.yml \ + --branch "$TAG" --limit 20 --json status \ + --jq '[.[] | select(.status != "completed")] | length') + if [ "$active" != 0 ]; then + echo "::notice::A Publish run for $TAG is still active (running or awaiting approval); not dispatching another." + echo "skip=1" >> "$GITHUB_OUTPUT" + exit 0 + fi + if [ "$TAG_SHA" != "$SHA" ]; then + echo "::error::$TAG points at $TAG_SHA, not $SHA, and pub.dev does not have it. Publishing it would ship a commit this run did not verify. Bump the version, or delete the tag if that publish never happened." + exit 1 + fi + - uses: actions/checkout@v4 + if: steps.state.outputs.skip != '1' with: ref: ${{ needs.plan.outputs.sha }} - uses: subosito/flutter-action@v2 + if: steps.state.outputs.skip != '1' with: flutter-version: ${{ needs.plan.outputs.flutter }} channel: stable cache: true - - run: flutter pub get + - name: flutter pub get + if: steps.state.outputs.skip != '1' + run: flutter pub get # Same checks as CI's package job. CI already passed on this commit; # repeating the package's own half costs a minute and means the tag is # placed by a job that saw the checks pass, not one that trusted a status. - name: dart analyze + if: steps.state.outputs.skip != '1' run: | dart analyze lib if [ -d test ]; then dart analyze test; fi - name: flutter test + if: steps.state.outputs.skip != '1' run: | if find test -name '*_test.dart' -print -quit 2>/dev/null | grep -q .; then flutter test @@ -135,6 +177,7 @@ jobs: # Exits non-zero on warnings; hints (such as the pubspec_overrides one # the firebase packages get) do not fail it. - name: flutter pub publish --dry-run + if: steps.state.outputs.skip != '1' run: flutter pub publish --dry-run - name: Tag ${{ matrix.tag }} @@ -147,6 +190,7 @@ jobs: -f sha="${{ needs.plan.outputs.sha }}" - name: Dispatch publish on ${{ matrix.tag }} + if: steps.state.outputs.skip != '1' env: GH_TOKEN: ${{ github.token }} run: | diff --git a/AUTHORING.md b/AUTHORING.md index 51dacaf..98514bf 100644 --- a/AUTHORING.md +++ b/AUTHORING.md @@ -270,8 +270,12 @@ OIDC; nothing to store as a secret). version by hand with `flutter pub publish`, then enable automated publishing for it on pub.dev (tag pattern `-v{{version}}`, `push` and `workflow_dispatch` events, environment `pub.dev`). -- To retry a failed publish, run **Release** from the Actions tab. It - re-dispatches publishing for any tagged version that pub.dev doesn't have yet. +- To retry a failed publish, run **Release** from the Actions tab on `main`. + It re-dispatches publishing for a tagged version that pub.dev doesn't have + yet, as long as the tag points at the tip of `main` and no Publish run for + it is still active. If `main` has moved on since the tag, bump the version + instead (or delete the tag if that publish never happened). +- **Publish** only publishes a tag whose commit is on `main`. The **Upstream compatibility** workflow runs daily. It tests every package against the newest upstream releases and the newest Flutter stable, and keeps From 69c8ea8e1a14f0d8981c96802c9b156257d27840 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Mehmet=20Ali=20Ustao=C4=9Flu?= Date: Sun, 8 Nov 2026 23:16:08 +0100 Subject: [PATCH 3/3] ci: isolate release verification, skip published versions, tighten lag test Release: - Split the release job. `verify` runs pub get, analyze, tests and the publish dry-run with a read-only token, no persisted credentials and no shared Flutter/pub cache; `tag` holds contents/actions write and runs no package code (no checkout). A per-package artifact marker carries the verified commit across, so one package failing does not hold back the others in the same merge. - The active-Publish check now runs before every dispatch, not only for existing tags. - matrix and step values reach run: blocks through env, not ${{ }}. Publish: - The on-main check uses `git merge-base --is-ancestor` against a full fetch instead of the compare API. - `resolve` skips publishing, green, when pub.dev already has the version, so a duplicate dispatch or a re-run cannot fail at upload. - dart-lang's reusable publish workflow is pinned to 6afc89d (v1). Its only inputs are environment and working-directory, so Flutter cannot be pinned to CI's version there. Upstream compatibility: - A dependency counts as held back only when our declared constraint excludes its newest release. SDK-pinned packages such as meta, and dependencies another package caps, no longer produce lag findings. - pub's exit code 69 (package server unavailable) is a tooling failure, alongside the existing network-error wording. --- .github/scripts/upstream_check.py | 111 ++++++++++++++---- .github/workflows/publish.yml | 51 +++++++-- .github/workflows/release.yml | 157 ++++++++++++++++++-------- .github/workflows/upstream-compat.yml | 5 +- 4 files changed, 237 insertions(+), 87 deletions(-) diff --git a/.github/scripts/upstream_check.py b/.github/scripts/upstream_check.py index 7809cdc..40cc859 100644 --- a/.github/scripts/upstream_check.py +++ b/.github/scripts/upstream_check.py @@ -50,8 +50,6 @@ LOG_TAIL = 80 STEP_TIMEOUT = 20 * 60 -# Ignored when copying packages/ to scratch: build output and resolution state -# that would make a scratch run differ from a fresh checkout. # pub's own wording when it could not talk to the package server. A resolve # step that fails with one of these says nothing about our package. NETWORK_ERROR = re.compile( @@ -68,37 +66,52 @@ class ToolingError(Exception): """The run cannot produce a trustworthy report (network, pub.dev down).""" +# Ignored when copying packages/ to scratch: build output and resolution state +# that would make a scratch run differ from a fresh checkout. COPY_IGNORE = shutil.ignore_patterns( ".dart_tool", "build", "pubspec.lock", ".flutter-plugins", ".flutter-plugins-dependencies", "Pods", ".symlinks", "DerivedData", ) -def run(cmd, cwd): - """(ok, combined output). Never raises for a failing command.""" +def run_rc(cmd, cwd): + """(exit code, combined output); the code is None when the command timed + out or could not start. Never raises for a failing command.""" try: proc = subprocess.run( cmd, cwd=cwd, stdout=subprocess.PIPE, stderr=subprocess.STDOUT, text=True, timeout=STEP_TIMEOUT, ) - return proc.returncode == 0, proc.stdout + return proc.returncode, proc.stdout except subprocess.TimeoutExpired as exc: out = exc.stdout or "" if isinstance(out, bytes): out = out.decode("utf-8", "replace") - return False, out + f"\n[timed out after {STEP_TIMEOUT}s]" + return None, out + f"\n[timed out after {STEP_TIMEOUT}s]" except OSError as exc: - return False, f"[could not run {cmd[0]}: {exc}]" + return None, f"[could not run {cmd[0]}: {exc}]" + + +def run(cmd, cwd): + """(ok, combined output). Never raises for a failing command.""" + code, out = run_rc(cmd, cwd) + return code == 0, out + + +# pub's exit code for "the package server could not be reached" (EX_UNAVAILABLE). +EXIT_UNAVAILABLE = 69 def resolve(cmd, cwd): """run() for a pub command that talks to the package server. A failure - caused by the network raises ToolingError instead of becoming a step.""" - ok, out = run(cmd, cwd) - if not ok and NETWORK_ERROR.search(out): - raise ToolingError(f"{' '.join(cmd)} in {cwd} hit a network error:\n" - + tail(out, 20)) - return ok, out + caused by the network raises ToolingError instead of becoming a step: + exit code 69 is pub saying so outright, and the wording check catches the + paths (flutter's wrapper, older pubs) that exit 1 for the same cause.""" + code, out = run_rc(cmd, cwd) + if code != 0 and (code == EXIT_UNAVAILABLE or NETWORK_ERROR.search(out)): + raise ToolingError(f"{' '.join(cmd)} in {cwd} could not reach the " + f"package server (exit {code}):\n" + tail(out, 20)) + return code == 0, out def tail(text, n=LOG_TAIL): @@ -136,15 +149,11 @@ def hosted_deps(pubspec_path, section="dependencies"): def outdated(pkg_dir): - """Direct hosted deps whose newest release lies outside the constraint. - - `pub outdated` already knows the difference: `upgradable` is the newest - version the current constraints allow, `latest` the newest stable release. - When they differ by a major (a minor below 1.0.0) for a direct - dependency, a constraint is what holds us back — ours, or a sibling's. - A newer release on the same line that pub could not pick (an SDK bound, a - transitive pin) is the current leg's business, not a new major, so it is - not a row. Prereleases are not counted — `latest` excludes them by default. + """Direct hosted deps whose newest release our own constraint excludes. + + `pub outdated` supplies `latest`, the newest stable release (prereleases + are not counted). A row needs our declared constraint to exclude it — see + excludes() for why `upgradable != latest` is not the test. """ ok, out = resolve(["flutter", "pub", "outdated", "--json", "--no-dev-dependencies"], pkg_dir) @@ -163,8 +172,7 @@ def outdated(pkg_dir): continue upgradable = (row.get("upgradable") or {}).get("version") latest = (row.get("latest") or {}).get("version") - if latest and upgradable != latest and not ( - upgradable and same_line(upgradable, latest)): + if latest and excludes(wanted[name], latest): rows.append({"package": name, "constraint": wanted[name], "upgradable": upgradable, "latest": latest}) return rows, out @@ -225,6 +233,61 @@ def example_checks(example_dir, steps, major): return ok +VERSION = re.compile(r"^(\d+)\.(\d+)\.(\d+)(?:-([0-9A-Za-z.-]+))?(?:\+[0-9A-Za-z.-]+)?$") +BOUND = re.compile(r"(>=|<=|>|<)\s*([0-9][0-9A-Za-z.+-]*)") + + +def version_key(text): + """Comparable key for a pub version, or None. A prerelease sorts below + its release; build metadata does not matter for constraint checks.""" + m = VERSION.match(text.strip()) + if not m: + return None + major, minor, patch, pre = m.groups() + return (int(major), int(minor), int(patch), 0 if pre else 1, pre or "") + + +def excludes(constraint, version): + """True when our declared `constraint` does not allow `version`. + + This, not `upgradable != latest`, is the test for "a constraint of ours + holds us back". `pub outdated` also reports a dependency as not + upgradable to latest when the SDK pins it (meta, collection) or another + package caps it, and those are not ours to widen — the current leg already + tests whatever pub can resolve. Handles what pubspecs here use: any, + ^x.y.z, exact versions and >=/>/ 0 else \ + (0, low[1] + 1, 0, 0, "") + return not (low <= want < high) + exact = version_key(c) + if exact is not None: + return exact[:3] != want[:3] + bounds = BOUND.findall(c) + if not bounds or BOUND.sub("", c).strip(): + return True + for op, text in bounds: + key = version_key(text) + if key is None: + return True + ok = {">=": want >= key, ">": want > key, + "<=": want <= key, "<": want < key}[op] + if not ok: + return True + return False + + def same_line(resolved, latest): """True when `resolved` is on `latest`'s caret line (^latest would allow it): same major, or same minor below 1.0.0.""" diff --git a/.github/workflows/publish.yml b/.github/workflows/publish.yml index f4c4c34..e3c78b8 100644 --- a/.github/workflows/publish.yml +++ b/.github/workflows/publish.yml @@ -34,22 +34,24 @@ jobs: outputs: package: ${{ steps.parse.outputs.package }} version: ${{ steps.parse.outputs.version }} + publish: ${{ steps.pubdev.outputs.publish }} steps: + # Full history so the ancestor check below sees all of main. - uses: actions/checkout@v4 + with: + fetch-depth: 0 + persist-credentials: false - name: Ensure PyYAML run: python3 -c "import yaml" 2>/dev/null || pip install --quiet pyyaml - name: Tagged commit is on main - env: - GH_TOKEN: ${{ github.token }} run: | set -euo pipefail - # identical: main is this commit; behind: main has it as an ancestor. - state=$(gh api "repos/$GITHUB_REPOSITORY/compare/main...$GITHUB_SHA" --jq .status) - case "$state" in - identical|behind) echo "$GITHUB_SHA is on main ($state)." ;; - *) echo "::error::$GITHUB_REF_NAME points at $GITHUB_SHA, which is not on main ($state). Only merged commits are published." - exit 1 ;; - esac + git fetch --quiet origin main + if ! git merge-base --is-ancestor "$GITHUB_SHA" FETCH_HEAD; then + echo "::error::$GITHUB_REF_NAME points at $GITHUB_SHA, which is not on main. Only merged commits are published." + exit 1 + fi + echo "$GITHUB_SHA is on main." - id: parse env: REF_TYPE: ${{ github.ref_type }} @@ -81,20 +83,45 @@ jobs: sys.exit(f"::error::Newest CHANGELOG heading is '{heading}', not {version}.") with open(os.environ["GITHUB_OUTPUT"], "a") as fh: fh.write(f"package={pkg}\nversion={version}\n") - print(f"Publishing {pkg} {version}") + print(f"Tag agrees with packages/{pkg}: {version}") PY + # A second dispatch, or a re-run after a publish that did go through, + # must not turn red at pub.dev's "version already exists". + - name: Already on pub.dev? + id: pubdev + env: + PACKAGE: ${{ steps.parse.outputs.package }} + VERSION: ${{ steps.parse.outputs.version }} + run: | + set -euo pipefail + code=$(curl -sS -o versions.json -w '%{http_code}' \ + -H 'Accept: application/vnd.pub.v2+json' "https://pub.dev/api/packages/$PACKAGE") + if [ "$code" != 200 ]; then + echo "::error::pub.dev answered HTTP $code for $PACKAGE; not deciding blind." + exit 1 + fi + if jq -e --arg v "$VERSION" 'any(.versions[]; .version == $v)' versions.json >/dev/null; then + echo "::notice::$PACKAGE $VERSION is already on pub.dev; nothing to publish." + echo "publish=false" >> "$GITHUB_OUTPUT" + else + echo "publish=true" >> "$GITHUB_OUTPUT" + fi + publish: name: ${{ needs.resolve.outputs.package }} ${{ needs.resolve.outputs.version }} needs: resolve + if: needs.resolve.outputs.publish == 'true' permissions: id-token: write # OIDC token for pub.dev # dart-lang's reusable workflow: one job in `environment` that checks out # the tag, installs Dart and the newest Flutter stable (not CI's pinned # version; Release's dry-run used the pinned one), then runs `pub get`, # `pub publish --dry-run` and `pub publish -f` with the OIDC token. Its - # only inputs are `environment` and `working-directory`. - uses: dart-lang/setup-dart/.github/workflows/publish.yml@v1 + # only inputs are `environment` and `working-directory`, so the Flutter + # version cannot be pinned to CI's FLUTTER_VERSION here. + # Pinned to the commit `v1` pointed at on 2026-11-08; bump deliberately. + uses: dart-lang/setup-dart/.github/workflows/publish.yml@6afc89df92d6eb3834022f73cd65adc8cdfcb92d # v1 with: environment: pub.dev working-directory: packages/${{ needs.resolve.outputs.package }} diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml index ca4bdfe..eac1f69 100644 --- a/.github/workflows/release.yml +++ b/.github/workflows/release.yml @@ -60,11 +60,14 @@ jobs: flutter: ${{ steps.flutter.outputs.version }} steps: - id: sha - run: echo "sha=${{ github.event.workflow_run.head_sha || github.sha }}" >> "$GITHUB_OUTPUT" + env: + SHA: ${{ github.event.workflow_run.head_sha || github.sha }} + run: echo "sha=$SHA" >> "$GITHUB_OUTPUT" - uses: actions/checkout@v4 with: ref: ${{ steps.sha.outputs.sha }} + persist-credentials: false # public repo: fetch and ls-remote need none # Only ever release what main points at. A workflow_run for an older # commit can arrive after a newer one has landed; its packages will be @@ -72,10 +75,12 @@ jobs: # A dispatch is on main already (see the job's `if`); checking it too # costs nothing and catches a push that landed while it queued. - name: Commit is still on main + env: + SHA: ${{ steps.sha.outputs.sha }} run: | git fetch --depth=1 origin main - if [ "$(git rev-parse FETCH_HEAD)" != "${{ steps.sha.outputs.sha }}" ]; then - echo "::notice::main has moved past ${{ steps.sha.outputs.sha }}; the newer run releases." + if [ "$(git rev-parse FETCH_HEAD)" != "$SHA" ]; then + echo "::notice::main has moved past $SHA; the newer run releases." echo "SKIP=1" >> "$GITHUB_ENV" fi @@ -98,14 +103,17 @@ jobs: fi python3 .github/scripts/release_plan.py . --github-output - release: - name: ${{ matrix.package }} ${{ matrix.version }} + # Runs third-party code (pub get resolves without a lockfile; tests run it), + # so it gets nothing it could abuse: a read-only token, no credentials left + # in .git/config, and no shared Flutter/pub cache that the upstream-compat + # runs (which resolve the newest upstream majors) could have populated. + verify: + name: verify ${{ matrix.package }} ${{ matrix.version }} needs: plan if: needs.plan.outputs.candidates != '[]' && needs.plan.outputs.candidates != '' runs-on: ubuntu-latest permissions: - contents: write # create the tag - actions: write # dispatch publish.yml + contents: read strategy: fail-fast: false matrix: @@ -114,59 +122,30 @@ jobs: run: working-directory: packages/${{ matrix.package }} steps: - # An existing tag: publish only what this run verifies, and never start - # a second Publish for a tag whose first one is still going. - - name: Tag state - id: state - if: ${{ matrix.tag_exists }} - working-directory: . - env: - GH_TOKEN: ${{ github.token }} - TAG: ${{ matrix.tag }} - TAG_SHA: ${{ matrix.tag_sha }} - SHA: ${{ needs.plan.outputs.sha }} - run: | - set -euo pipefail - active=$(gh run list --repo "$GITHUB_REPOSITORY" --workflow publish.yml \ - --branch "$TAG" --limit 20 --json status \ - --jq '[.[] | select(.status != "completed")] | length') - if [ "$active" != 0 ]; then - echo "::notice::A Publish run for $TAG is still active (running or awaiting approval); not dispatching another." - echo "skip=1" >> "$GITHUB_OUTPUT" - exit 0 - fi - if [ "$TAG_SHA" != "$SHA" ]; then - echo "::error::$TAG points at $TAG_SHA, not $SHA, and pub.dev does not have it. Publishing it would ship a commit this run did not verify. Bump the version, or delete the tag if that publish never happened." - exit 1 - fi - - uses: actions/checkout@v4 - if: steps.state.outputs.skip != '1' with: ref: ${{ needs.plan.outputs.sha }} + persist-credentials: false - uses: subosito/flutter-action@v2 - if: steps.state.outputs.skip != '1' with: flutter-version: ${{ needs.plan.outputs.flutter }} channel: stable - cache: true + cache: false - name: flutter pub get - if: steps.state.outputs.skip != '1' run: flutter pub get # Same checks as CI's package job. CI already passed on this commit; # repeating the package's own half costs a minute and means the tag is - # placed by a job that saw the checks pass, not one that trusted a status. + # placed after a job that saw the checks pass, not one that trusted a + # status. - name: dart analyze - if: steps.state.outputs.skip != '1' run: | dart analyze lib if [ -d test ]; then dart analyze test; fi - name: flutter test - if: steps.state.outputs.skip != '1' run: | if find test -name '*_test.dart' -print -quit 2>/dev/null | grep -q .; then flutter test @@ -177,34 +156,114 @@ jobs: # Exits non-zero on warnings; hints (such as the pubspec_overrides one # the firebase packages get) do not fail it. - name: flutter pub publish --dry-run - if: steps.state.outputs.skip != '1' run: flutter pub publish --dry-run + # Matrix legs cannot pass outputs to another matrix, and `needs` is all + # or nothing. A marker per verified package lets `tag` release the + # packages that passed even when another one in the same merge failed. + - name: Record verification + working-directory: . + env: + SHA: ${{ needs.plan.outputs.sha }} + PACKAGE: ${{ matrix.package }} + run: | + mkdir -p verified + printf '%s\n' "$SHA" > "verified/$PACKAGE" + - uses: actions/upload-artifact@v4 + with: + name: verified-${{ matrix.package }} + path: verified/ + retention-days: 1 + + # Holds the write permissions and runs no package code: no checkout, no pub, + # only gh calls on the plan's metadata. + tag: + name: tag ${{ matrix.package }} ${{ matrix.version }} + needs: [plan, verify] + if: ${{ !cancelled() && needs.verify.result != 'skipped' }} + runs-on: ubuntu-latest + permissions: + contents: write # create the tag + actions: write # dispatch publish.yml, list its runs + strategy: + fail-fast: false + matrix: + include: ${{ fromJSON(needs.plan.outputs.candidates) }} + steps: + - uses: actions/download-artifact@v4 + with: + name: verified-${{ matrix.package }} + path: verified + continue-on-error: true # absent when this package's verify failed + + - name: Verified on this commit + env: + SHA: ${{ needs.plan.outputs.sha }} + PACKAGE: ${{ matrix.package }} + run: | + if [ "$(cat "verified/$PACKAGE" 2>/dev/null)" != "$SHA" ]; then + echo "::error::$PACKAGE was not verified on $SHA (see its verify job); not tagging or publishing it." + exit 1 + fi + + # Publish only what this run verified, and never start a second Publish + # for a tag whose first one is still going (running, or waiting for + # approval in the pub.dev environment). + - name: Tag state + id: state + env: + GH_TOKEN: ${{ github.token }} + TAG: ${{ matrix.tag }} + TAG_EXISTS: ${{ matrix.tag_exists }} + TAG_SHA: ${{ matrix.tag_sha }} + SHA: ${{ needs.plan.outputs.sha }} + run: | + set -euo pipefail + if [ "$TAG_EXISTS" = true ]; then + active=$(gh run list --repo "$GITHUB_REPOSITORY" --workflow publish.yml \ + --branch "$TAG" --limit 20 --json status \ + --jq '[.[] | select(.status != "completed")] | length') + if [ "$active" != 0 ]; then + echo "::notice::A Publish run for $TAG is still active (queued, running or awaiting approval); not dispatching another." + echo "skip=1" >> "$GITHUB_OUTPUT" + exit 0 + fi + if [ "$TAG_SHA" != "$SHA" ]; then + echo "::error::$TAG points at $TAG_SHA, not $SHA, and pub.dev does not have it. Publishing it would ship a commit this run did not verify. Bump the version, or delete the tag if that publish never happened." + exit 1 + fi + fi + - name: Tag ${{ matrix.tag }} if: ${{ !matrix.tag_exists }} env: GH_TOKEN: ${{ github.token }} + TAG: ${{ matrix.tag }} + SHA: ${{ needs.plan.outputs.sha }} run: | - gh api "repos/${{ github.repository }}/git/refs" \ - -f ref="refs/tags/${{ matrix.tag }}" \ - -f sha="${{ needs.plan.outputs.sha }}" + gh api "repos/$GITHUB_REPOSITORY/git/refs" -f ref="refs/tags/$TAG" -f sha="$SHA" - name: Dispatch publish on ${{ matrix.tag }} if: steps.state.outputs.skip != '1' env: GH_TOKEN: ${{ github.token }} + TAG: ${{ matrix.tag }} + PACKAGE: ${{ matrix.package }} + VERSION: ${{ matrix.version }} run: | - gh workflow run publish.yml --repo "${{ github.repository }}" --ref "${{ matrix.tag }}" - echo "Publishing ${{ matrix.package }} ${{ matrix.version }} — follow it under the Publish workflow." >> "$GITHUB_STEP_SUMMARY" + gh workflow run publish.yml --repo "$GITHUB_REPOSITORY" --ref "$TAG" + echo "Publishing $PACKAGE $VERSION — follow it under the Publish workflow." >> "$GITHUB_STEP_SUMMARY" # Packages whose metadata release_plan.py rejected (version not on top of # CHANGELOG.md, not newer than pub.dev, ...). Kept out of `plan` so the # healthy packages in the same merge still release, but the run ends red. problems: - needs: [plan, release] + needs: [plan, tag] if: ${{ !cancelled() && needs.plan.result == 'success' && needs.plan.outputs.problems != '0' }} runs-on: ubuntu-latest steps: - - run: | - echo "::error::${{ needs.plan.outputs.problems }} package(s) were not released; see the plan job's errors." + - env: + PROBLEMS: ${{ needs.plan.outputs.problems }} + run: | + echo "::error::$PROBLEMS package(s) were not released; see the plan job's errors." exit 1 diff --git a/.github/workflows/upstream-compat.yml b/.github/workflows/upstream-compat.yml index aaf55cc..dd23bce 100644 --- a/.github/workflows/upstream-compat.yml +++ b/.github/workflows/upstream-compat.yml @@ -104,7 +104,8 @@ jobs: - name: Check against newest upstream env: RUN_URL: ${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }} - run: python3 .github/scripts/upstream_check.py . "${{ matrix.package }}" --out reports + PACKAGE: ${{ matrix.package }} + run: python3 .github/scripts/upstream_check.py . "$PACKAGE" --out reports - uses: actions/upload-artifact@v4 with: @@ -136,7 +137,7 @@ jobs: run: | set -euo pipefail # shellcheck disable=SC2086 # DRY_RUN is empty or one flag - python3 .github/scripts/upstream_issues.py reports --repo "${{ github.repository }}" $DRY_RUN + python3 .github/scripts/upstream_issues.py reports --repo "$GITHUB_REPOSITORY" $DRY_RUN - name: Summary run: | {