# Remote-release recipe (`mgf-fed release-remote`)

> **Audience:** maintainer promoting a **locally-validated** version to the self-hosted devpi index.
> **Closes / enforces:** REL-01 (annotated tag), REL-02 (build-once / no version reuse), REL-05
> (immutable once published), REL-06 (strictly-ordered flow), REL-08 (smoke the wheel), REL-13
> (federation consistency gate) in [`docs/standards/RELEASING.md`](../standards/RELEASING.md); PKG-04
> (publish flow) + PKG-05 (index verify, never pypi.org) in [`PACKAGE_DISTRIBUTION.md`](../standards/PACKAGE_DISTRIBUTION.md).
> **Tooling:** `mgf-fed release-remote` (`--dry-run` to preview); the devpi publish password in `$DEVPI_PASSWORD`.
> **History:** Codified 2026-06-11 alongside the two-mode release model (federation automation plan, Phase 3).

---

## Pre-requisite — local release first

Remote release **promotes the same wheel** that the local-release gate already built and
validated ([`local-release.md`](local-release.md)). `release-remote` refuses to publish a version
that isn't in the local index (*"no local release of X — run `release-local X` first"*). This is
the build-once invariant (REL-02): the artifact promoted to devpi is byte-identical to the one
validated locally — never a fresh rebuild from a later commit.

All mgf-* **dependencies** must already be remote-published (wave order on the remote side).

## The gate (what `release-remote` runs, per library, in wave order)

| # | Stage | Rule |
|---|---|---|
| 0 | **pre-req** | the build-once wheel is in the local index; working tree clean; **idempotent already-published index check** (skip if the version is already live) |
| 1 | **tag** | annotated `v<version>` on the build commit, then push (REL-01) |
| 2 | **publish** | `uv publish --publish-url …/magogi/prod/` the **same** wheel to the devpi index (PKG-04, REL-06 ordering) |
| 3 | **verify** | the version appears in the `+simple/` index listing — never pypi.org (PKG-05) |
| 4 | **registry** | regenerate + `--check` `MGF_LIBRARIES` so the federation stays consistent (REL-13) |

> The index verify is the canonical "is it live?" gate (PKG-05). A passing local smoke (REL-08)
> proves the wheel installs; the `+simple/` listing proves it's actually resolvable from the index.

## Run it

```sh
export DEVPI_PASSWORD=...             # the magogi account's devpi publish password (REL-04 / PKG-03)

# preview — pre-req checks + plan, no tag/publish:
mgf-fed release-remote mgf-http --dry-run

# promote (after a green local release of the same version):
mgf-fed release-remote mgf-http
```

`--dry-run` reports each library's state: *already published* (idempotent no-op), *absent*
(would tag + publish), or *no local release* (run `release-local` first). It never tags or uploads.

## Invariants this enforces

- **Build-once / promote** — the remote artifact == the locally-validated artifact (REL-02).
- **Immutable** — a published version is never content-swapped; bugs ship as a new version (REL-05).
- **Ordered** — bump → local-release → tag → publish → index-verify → registry; never inverted (REL-06).
- **Consistent** — releasing any library leaves the whole federation registry consistent (REL-13).
