Release process follow-ups from 1.4.1 post-mortem

[randlee]

Follow-ups from the 1.4.1 release post-mortem (docs/postmortems/1.4.1-release.md, PR #468).

1. Break up the publishing workflow

release.yml is one monolithic job chain (gate -> tag -> crates.io -> PyPI -> Homebrew -> winget), so a failure or gap in any one channel (winget) blocks or skips everything downstream of it, and a partial failure can't be retried in isolation. Split per-channel publish steps so each can be dispatched/retried independently once the release itself is tagged and the core artifacts (crates.io, GitHub Release) are published.

2. Every channel needs a concrete fix/retry path

winget was "unrecoverable-by-design once a release completes" — no standalone dispatch existed, so a wiring bug (wrong secret) plus no retry path meant it silently failed across 4 releases (1.0.0, 1.4.0, 1.4.1) with no way to fix forward without a full re-release. Same risk likely applies to Homebrew/PyPI. Each publish channel needs its own decoupled, safe-to-re-run path (see release/winget-standalone-dispatch for the winget instance of this).

3. Release -> main should not depend on me

Currently release-track fixes and merges to main require me (Rand) to be present to approve/watch CI cycles. Reduce the human-in-the-loop dependency for routine release-track PRs (docs, gate fixes, wiring fixes) so the pipeline can progress unattended, with escalation only for genuinely ambiguous or risky decisions.

[randlee]

4. Preflight must run before merge to develop, not after

Preflight should run before merging to develop (or on develop) and verify the change will not hit blocking issues on main — not discovered after the fact during release. This is what let the release-gate ancestry gap reach the release step in the first place.

Approval model

• develop -> main: requires my approval.
• release/* -> main: approval can be dropped — still must pass CI, no exceptions.

[randlee]

Reviewed from the publisher side. Agreed on all three items. Two additions, and one correction to something I said during the release.

Correction: winget's user-facing state is better than I reported

I told team-lead that winget "has never shipped from this repo" and that the catalog was "stale by several versions", and suggested backfilling intermediate versions. That was wrong, and I should have checked winget-pkgs before saying it.

The workflow's publish-winget job has indeed never succeeded — that part holds. But the packages reached the catalog anyway, by manual submission:

• microsoft/winget-pkgs currently carries randlee.sc-compose 1.0.1 and 1.4.0
• both were submitted manually by @randlee (upstream PRs 362639 and 416501; 416501 merged 2026-08-12)

So the catalog is exactly one version behind, not several, and no backfill is needed — only 1.4.1. The post-mortem doc (docs/postmortems/1.4.1-release.md:12-15) states this correctly; it's the issue-body phrasing "silently failed across 4 releases ... with no way to fix forward" that reads as though users never received the package. The automation failed silently across those releases; delivery was rescued by hand each time. That's still worth fixing — it just isn't a user-facing outage, and it lowers the severity.

Addition to item 1: a new dispatch workflow must live on the default branch

Not in the issue, and it bit us immediately after #467 merged. Dispatching the new standalone workflow failed:

HTTP 404: workflow winget-publish.yml not found on the default branch

This repo's default branch is develop. workflow_dispatch only registers workflows present there. #467 merged winget-publish.yml into main only, so it was un-dispatchable; release.yml and release-preflight.yml work solely because they also exist on develop. Fixed by #470 (main -> develop).

This interacts badly with the release-branch-off-main rule: any release-infra PR that adds or renames a dispatchable workflow is only half-landed when it merges to main. If item 1 splits release.yml into per-channel dispatch workflows, every one of them hits this. Worth stating explicitly in the release docs.

Addition to item 2: partial status

• PyPI — partially closed. ci(release): add standalone winget publish workflow #467 added --skip-existing to both maturin upload calls, so publish-pypi is now re-runnable. Previously a re-run failed on already-uploaded files, and since release needs publish-pypi and publish-winget needs release, winget was skipped rather than run — that dependency chain, not just the token bug, is why v1.4.1 had no recovery path.
• Homebrew — still has no standalone path. Same shape as winget was.
• crates.io — already safe; the publish job's publish_if_missing skips already-published crates.

On item 3

The concrete blocker is branch protection requiring 1 approving review on main, which an agent cannot self-satisfy. Worth solving deliberately rather than by loosening protection — e.g. a scoped CODEOWNERS or an approval path for release-infra paths only (.github/workflows/, scripts/release_*, docs/release-*). I'd rather keep the human gate on anything that publishes than trade it for unattended throughput.

[randlee]

Feedback on item 4 and the approval model. Agreed on the direction of both, but the approval change has a concrete prerequisite that isn't in place today.

Approval model: "still must pass CI" is not currently enforceable on main

I checked main's protection before answering:

$ gh api repos/randlee/sc-compose/branches/main/protection
{"enforce_admins":true,"required_checks":null,"restrictions":null,"reviews":1}

required_status_checks is null. There are no required status checks on main at all. The only thing gating a merge today is the single approving review. (The one active ruleset, "Protect integration branches", covers refs/heads/integrate/* and refs/heads/integration/* only, with deletion and non_fast_forward rules — it contributes nothing to main.)

So dropping approval for release/* -> main as things stand doesn't move the gate from human to CI — it removes the only gate. Checks would still run and still render red, but nothing would block merging on red. Given main is the branch the release workflow publishes from, using stored crates.io/PyPI/Homebrew/winget tokens, that's the one branch where I'd least want an unenforced gate.

Sequencing I'd suggest, and I'd treat it as strictly ordered:

1. Add required status checks on main first — at minimum Format check, clippy, test (ubuntu-latest), manifest-validation (ubuntu). Verify a red PR is actually blocked.
2. Only then drop required_approving_review_count to 0 for the release/* case.

Doing (2) before (1) is a strict regression in safety, not a neutral trade.

Second concern: release/* becomes a privilege boundary

Branch protection discriminates by name, so "approval not required for release/*" means anyone or anything that can push a branch named release/… can merge to main unreviewed. That namespace then carries real privilege, and nothing today constrains who creates it or what it may touch.

The sharper edge: release/* PRs are exactly the ones that legitimately edit .github/workflows/. An unreviewed release/* PR could weaken release.yml, or weaken the very required checks from step 1, and then merge itself. #467 — mine — modified release.yml and a test that pins its invariants; under the proposed model that merges with no human ever looking at it.

Two options, either acceptable:

• Keep approval required when a PR touches .github/workflows/, scripts/release_*, or release/publish-artifacts.toml, via CODEOWNERS; drop it for everything else on release/*. This preserves unattended progress for docs, gate-script, and wiring fixes — which is what item 3 actually asks for — while keeping eyes on changes that alter publishing behavior.
• Or drop approval broadly but make the workflow-invariant tests required checks, so a workflow edit can't land while contradicting its pinned assertions.

I'd take the first. Note that neither fully closes it: an unreviewed PR can edit CODEOWNERS itself unless that path is also protected.

Item 4: preflight before merge — agreed, but it needs splitting first

Agreed on the principle. One practical obstacle: Release Preflight can't be run wholesale on every develop-bound PR, because it calls check-version-unpublished. The moment a version ships, that check fails by design — I confirmed this against main after 1.4.1 published:

release version already published for: sc-compose, sc-composer, sc-sha

Run as-is pre-merge, preflight would fail on every develop PR from a release until the next version bump, and a permanently-red gate is one people learn to ignore.

The distinction that matters is between two kinds of check currently mixed together:

• Structural invariants — true at every commit: fmt, clippy, tests, manifest completeness, publish-order graph, version lockstep, README/version agreement. These should run on every PR to develop. Lockstep and README-version in particular are cheap, and README-version currently runs only inside release_gate.sh, so today it's first evaluated during the release itself.
• Release-time predicates — only meaningful at release: version unpublished, main/develop parity. These can't move earlier without being wrong.

So the actionable form of item 4 is: extract the structural half of release_gate.sh into a script CI runs on every develop PR, and leave the release-time half in the gate. That closes the "discovered after the fact" gap for everything that can be known early.

On the specific failure that motivated this: the ancestry gap wouldn't have been caught by running preflight earlier, because preflight never contained that check — it lived only in release_gate.sh. #465 has since changed it to compare content parity rather than commit ancestry, which fixes the actual defect. Worth being precise that item 4 wouldn't have prevented that incident; it prevents a different and broader class.

One more, from tonight

Whatever splits out of release.yml under item 1 must exist on the default branch (develop) to be dispatchable at all — workflow_dispatch resolves via the default branch, not via -r. This already bit winget-publish.yml, which merged to main in #467 and 404'd on dispatch. Combined with the release-branch-off-main rule, every new per-channel workflow will land half-usable unless the sync to develop is treated as part of the same change rather than routine follow-up.