Cleaning up deployment snapshots
Remove superseded prerelease documentation when its exact stable release is published, without disturbing other versions or retry safety.
Versioned documentation snapshots were append-only. A beta such as 3.4.0b1 could stay deployed and visible after stable 3.4.0 was published.
This contribution proposes cleaning up only the alpha, beta, and release-candidate snapshots for that exact stable release. The difficult part is preserving publication guarantees while removing stale routes and inventory entries.
Match the exact release, not a broad prefix
Publishing 3.4.0 can remove 3.4.0a1, 3.4.0b12, and 3.4.0rc2. It must preserve other patch or minor releases, unrelated prereleases, and stable snapshots.
prerelease = re.compile(re.escape(identifier) + r"(?:a|b|rc)[0-9]+")
superseded = [
str(entry.version)
for entry in versions
if prerelease.fullmatch(str(entry.version))
]Escaping the stable identifier and using fullmatch keeps the candidate set tied to one release. Multi-digit prerelease suffixes are included without broad directory or minor-line deletion.
One deployment update, not a partial state
Mike’s ordinary deploy and delete commands each create a commit. Running them separately would expose an intermediate state where the stable release is published but cleanup has not completed.
The proposed publisher uses Mike’s Git primitives to put stable publication, alias updates, inventory changes, and prerelease removal into one Git commit. Missing or malformed inventory fails before cleanup; prereleases with unexpected alias ownership are not silently removed.
Stable content remains immutable. An identical existing stable snapshot can clean up retained prereleases without rewriting its content. Different content is rejected. Once publication and cleanup have succeeded, an identical retry is a no-op.
Regression coverage for publication guarantees
Tests exercise real Mike publication in temporary Git repositories. They check exact alpha/beta/RC removal, unrelated-version preservation, one-commit publication, immutable stable content, forward-only aliases, and retry behaviour.
An injected inventory-write failure verifies that the combined update leaves the deployment branch unchanged and allows a later successful retry.
| Reported local validation | Result |
|---|---|
| Relevant versioned-documentation tests | 24 passed |
| Ruff lint and formatting | Passed |
| Applicable pre-commit hooks | Passed |
| git diff --check | Passed |
Implementation available for review
PR #10563 contains the publisher change, documentation, and regression tests. It remains open. The implementation preserves the existing publication model while adding exact cleanup; it does not claim that deployment changes have already shipped upstream.
Mahaboob AshrafSoftware & AI Engineer · Hyderabad, India
