diff --git a/.github/scripts/release_plan.py b/.github/scripts/release_plan.py new file mode 100644 index 0000000..0194a36 --- /dev/null +++ b/.github/scripts/release_plan.py @@ -0,0 +1,196 @@ +#!/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, +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 +--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 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, 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): + """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 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 = {} + for line in proc.stdout.splitlines(): + 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 + + +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, + "tag_sha": tags.get(tag, "")}) + 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..40cc859 --- /dev/null +++ b/.github/scripts/upstream_check.py @@ -0,0 +1,499 @@ +#!/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: 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 +""" + +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 + +# 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).""" + + +# 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_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, proc.stdout + except subprocess.TimeoutExpired as exc: + out = exc.stdout or "" + if isinstance(out, bytes): + out = out.decode("utf-8", "replace") + return None, out + f"\n[timed out after {STEP_TIMEOUT}s]" + except OSError as 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: + 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): + 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 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) + 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 excludes(wanted[name], 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 = resolve(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 + + +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.""" + 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 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. + + `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 = 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 + + +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 = 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) + 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, 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): + 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"], caret_line(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 + + 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}-") + 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 = resolve(["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..0432bc9 --- /dev/null +++ b/.github/scripts/upstream_issues.py @@ -0,0 +1,228 @@ +#!/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, hand-closed issue, same print + leave it closed: a maintainer closed it + knowing about exactly this finding + 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. 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] + +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"") +AUTO_CLOSED = "" +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 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) + if status == "ok": + 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'}). " + "Closing."]) + else: + print(f"{pkg}: ok") + return + body = render(report) + 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']}") + 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 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: + 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..e3c78b8 --- /dev/null +++ b/.github/workflows/publish.yml @@ -0,0 +1,127 @@ +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. +# 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: + 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 }} + 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 + run: | + set -euo pipefail + 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 }} + 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"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`, 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 new file mode 100644 index 0000000..eac1f69 --- /dev/null +++ b/.github/workflows/release.yml @@ -0,0 +1,269 @@ +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). 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: + 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.ref == 'refs/heads/main') || + (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 + 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 + # 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 + env: + SHA: ${{ steps.sha.outputs.sha }} + run: | + git fetch --depth=1 origin main + 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 + + # 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 + + # 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: read + 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 }} + persist-credentials: false + + - uses: subosito/flutter-action@v2 + with: + flutter-version: ${{ needs.plan.outputs.flutter }} + channel: stable + cache: false + + - name: flutter pub get + 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 after 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 + + # 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/$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 "$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, tag] + if: ${{ !cancelled() && needs.plan.result == 'success' && needs.plan.outputs.problems != '0' }} + runs-on: ubuntu-latest + steps: + - 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 new file mode 100644 index 0000000..dd23bce --- /dev/null +++ b/.github/workflows/upstream-compat.yml @@ -0,0 +1,149 @@ +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 }} + PACKAGE: ${{ matrix.package }} + run: python3 .github/scripts/upstream_check.py . "$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..98514bf 100644 --- a/AUTHORING.md +++ b/AUTHORING.md @@ -252,6 +252,36 @@ 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 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 +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)