[MAUstaoglu]

Two automations for this repo: daily alerts when a newer upstream release or a new Flutter stable breaks or excludes one of our plugins, and automatic publishing to pub.dev when a version bump lands on main.

Upstream compatibility (upstream-compat.yml)

Runs daily at 05:17 UTC. It can also be started by hand, with optional inputs to check a single package, pick a Flutter version, or do a dry run. It always uses the newest Flutter stable, unlike CI, which is pinned.

For each package, .github/scripts/upstream_check.py runs two passes on a scratch copy of packages/:

• current: flutter pub upgrade, the newest releases within our constraints.
• major: only when pub outdated shows a newer major outside our constraint. It runs pub upgrade --major-versions on our direct dependencies. That command quietly stays on the old major when something else blocks the new one, so for anything left behind the pass also runs pub add <dep>:^<latest>. That way the pass either tests the new major for real or records pub's explanation of what is blocking it.

Each pass then runs the same checks as the CI package job: analyze lib and test, flutter test, and resolve and analyze the example. Every package gets one of these results:

result	meaning
broken	fails within our current constraints; users are affected now
major-breaks	a new upstream major exists outside our constraint, and moving to it fails
lag	a new upstream major exists outside our constraint, and moving to it passes; widening the constraint is the fix
ok	nothing to do

.github/scripts/upstream_issues.py keeps one issue per package (Upstream compatibility: <package>, label upstream-compat). The issue body carries a hidden fingerprint of the finding:

• An open issue is edited only when the fingerprint changes. An unchanged finding produces no edit and no comment.
• The issue closes itself once the package passes again.
• A finding identical to one a maintainer closed by hand stays closed. A different finding opens a new issue.
• An issue the workflow closed itself is marked auto-closed, so the same finding coming back later opens a new issue rather than staying silent.
• Upstream versions count by caret line: an upstream patch or minor does not touch open issues; a new major does.
• 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, don't produce findings.
• If the check script itself fails (for example, pub.dev is unreachable: pub's exit code 69 or its network errors in a resolve step), that package's job goes red and no issue is filed.

Expect a batch of firebase issues on the first run

A local run on Flutter 3.47.9 found that firebase_auth_tvos can't move to firebase_auth 7.0.1. That version needs firebase_core ^5.1.0, but firebase_core_tvos pins ^4.13.0. Every package that depends on firebase_core_tvos will probably report the same major-breaks on the first run, so expect several issues at once. They all point to the same fix: port firebase_core_tvos to firebase_core 5. In the same run, shared_preferences_tvos and url_launcher_tvos came back ok.

Auto-publish (release.yml → publish.yml)

release.yml runs after CI succeeds on a push to main, or when started by hand to retry. .github/scripts/release_plan.py picks every package whose pubspec version isn't on pub.dev yet. Such a version must also:

• match the newest ## heading in CHANGELOG.md, and
• be newer than every version already on pub.dev.

If either check fails, that package isn't released and the run ends red. Healthy packages in the same merge still go out.

Each release candidate goes through two jobs:

• verify re-runs pub get, analyze, tests and flutter pub publish --dry-run on that exact commit. Because this runs third-party code, it gets a read-only token, no credentials persisted in .git/config, and no shared Flutter/pub cache.
• tag holds the write permissions (contents, actions) and runs no package code (no checkout). It creates the tag <package>-v<version> and starts publish.yml on that tag, but only for packages whose verify passed. One failing package doesn't hold back the others.

Why the release workflow starts the publish workflow itself: a tag created with GITHUB_TOKEN doesn't trigger on: push workflows, but GITHUB_TOKEN is allowed to start a workflow_dispatch run. pub.dev accepts publishing from a workflow_dispatch run on a tag ref when that event is enabled for the package. So no PAT or GitHub App is needed. Pushing a tag by hand also triggers publish.yml directly.

Started by hand, Release runs only on main. No Publish is dispatched while one for the same tag is still queued, running or awaiting approval. A tag that already exists is re-dispatched only when it points at the commit just verified; a tag on an older commit fails the run with "bump the version or delete the tag".

publish.yml checks that the tagged commit is an ancestor of main (git merge-base --is-ancestor) and that the tag matches the pubspec version and the changelog. If pub.dev already has that version, it stops there, green. Otherwise it calls dart-lang's reusable publish.yml, pinned to commit 6afc89d (v1), which publishes over OIDC in the pub.dev environment. That workflow only accepts environment and working-directory, so it installs the newest Flutter stable rather than CI's pinned version. Release's dry-run uses the pinned one.

Today all 25 packages match their pub.dev versions, so merging this releases nothing.

pub.dev setup (manual, per package)

On pub.dev/packages/<pkg>/admin → Automated publishing → GitHub Actions:

• Enable publishing from GitHub Actions, with repository fluttertv/plugins
• Set the tag pattern to <pkg>-v{{version}}
• Enable both the push and workflow_dispatch events. Without workflow_dispatch, automatic releases fail at upload.
• Require the GitHub Actions environment pub.dev (recommended)

On GitHub:

• Settings → Environments → create pub.dev, and under Deployment branches and tags choose Selected branches and tags with a tag rule *_tvos-v*. That way only release tags can deploy to it. Required reviewers are optional.
• Make sure no tag ruleset stops github-actions from creating *_tvos-v* tags.

A brand-new package still needs its first version published by hand (flutter pub publish), because pub.dev only allows automated publishing for packages that already exist.

Also in this PR

• AUTHORING.md: a new "7. Releasing" section
• .gitignore: __pycache__/

Tested

• release_plan.py: covered a version bump, a missing changelog entry, a version older than pub.dev, and an already-existing tag. On main today it finds nothing to release.
• Issue deduplication: all six open/closed/same/changed cases, using a stubbed gh. Also a --dry-run against this repo's real issues.
• check_repo.py --selftest still passes.
• After the independent review: scenario tests with stubbed gh/flutter for auto-close vs hand-close, reopened issues, patch vs major fingerprints, the network-error exit, build-metadata ordering and annotated-tag SHAs.
• Second review round: release-plan cases incl. tag SHAs, pub build-metadata ordering, constraint-based lag detection (meta-style SDK pins, ranges, carets below 1.0), exit 69, bot-closed vs hand-closed issues, plus the release Tag state step (tag on another commit, active Publish run) and the pub.dev already-published step run as-is with a stubbed gh and the real pub.dev API.
• Not yet tested: none of these workflows has run on GitHub yet. After merge, a manual dry run of Upstream compatibility is the first thing to try.