Skip to content
rlsbl.mirror_publication
Updated
On this page

Publishes one released version on a subtree mirror: its standalone tag at the subtree split of the recorded release commit, then its Release. A tag is never moved.

#rlsbl.mirror_publication

#rlsbl.mirror_publication

Publishing one released version onto a subtree mirror.

A mirror is the standalone repository a monorepo sub-project's subtree is split into. Its BRANCH is the mirror reconciler's business (:mod:rlsbl.commands.monorepo.mirror_cmd): tool-owned, force-pushed with a lease, exactly one scaffold commit atop the current split. Its TAGS and its GitHub Releases are this module's, and nothing else writes them -- a mirror scaffold deliberately ships no publish workflow, and the reconciler sweeps any publish workflow that reaches the mirror another way (an older scaffold layer's leftover, or one carried in by the subtree split), so a mirror never releases itself.

The commit correspondence -------------------------

A version's commit on the mirror is derived, never guessed. The release record ties every released version to the monorepo commit it shipped from (the archive's candidate_sha, the commit CI proved green), and the subtree split is a deterministic function from a monorepo commit to the mirror commit carrying that commit's subtree state::

mirror commit for version V == git subtree split --prefix

The split is incremental and content-derived, so the split of an ancestor is an ancestor of the split of HEAD: a tag materialized this way always names a commit the converged mirror already carries. Nothing here computes a commit any other way, and nothing accepts one from a caller.

What the Release carries ------------------------

The document is :mod:rlsbl.release_publication's -- the same authority the monorepo's own Release uses, so the two can never disagree about what a Release body looks like. One thing differs, and it is the point of the correspondence above: the rlsbl-ci-sha marker on a MIRROR Release names the SPLIT commit, because a marker naming the monorepo's release commit would name a commit that does not exist in the repository the Release is attached to.

Idempotence, and the one refusal --------------------------------

Everything here can be re-run: a tag already at the right commit is left alone, and a Release that already exists has its marker reconciled rather than being created a second time. The single refusal is a tag that already exists on the mirror at a DIFFERENT commit -- a released tag is never moved, so that is a hard error naming both commits and the operator decides.

#MirrorPublicationError

A mirror tag or Release could not be published.

#split_commit_for

python
def split_commit_for(root, subtree_path, source_sha, *, timeout=SPLIT_TIMEOUT)

The mirror commit corresponding to monorepo commit source_sha.

A branchless git subtree split AT that commit: it prints the synthetic commit's SHA, creates no ref, and materializes the split ancestry as loose objects in the monorepo's object store. Deterministic, so two callers asking the same question get the same answer, and the answer for an ancestor is an ancestor of the answer for HEAD.

--prefix and the path are separate tokens because that is the spelling rlsbl's observe allowlist pins (see :mod:rlsbl.observe_allowlist); the stuck --prefix=<path> form would be refused above a preview's no-writes line.

#split_map_for

python
def split_map_for(root, subtree_path, source_shas, *, timeout=SPLIT_TIMEOUT)

{source sha: split sha} for every commit in source_shas.

One split per distinct commit. The subtree cache makes everything after the first walk cheap, and asking per commit is what keeps the map HONEST: each entry is the split git itself computed for that commit, never an offset guessed from another entry.

#mirror_tag

python
def mirror_tag(version, *, target)

The tag the mirror carries for version.

The mirror is a STANDALONE repository, so the tag is the target's standalone form (v1.2.3) -- never the workspace's {name}@v{version} scheme, which is exactly what a consumer resolving the mirror by URL cannot read.

#remote_refs

python
def remote_refs(remote, cwd, *, timeout=PUSH_TIMEOUT)

Every ref the mirror remote carries, as {refname: sha}.

Peeled tag entries (refs/tags/x^{}) replace their annotated-tag object with the commit the tag points at, which is the sha a comparison against a split commit has to use.

#parse_ls_remote

python
def parse_ls_remote(text)

{refname: sha} from git ls-remote output, peeling tags.

#remote_tag_commits

python
def remote_tag_commits(refs)

{tag name: commit} from a ref map.

#push_tag

python
def push_tag(remote, commit, tag, cwd, *, timeout=PUSH_TIMEOUT)

Create tag on the mirror at commit. Never moves an existing one.

--no-verify: the monorepo's pre-push hook guards ITS changelog coverage, which says nothing about a derived artifact's tag namespace. This is the tool declining its own hook on an internal operation, not a user-facing escape hatch.

#ensure_tag

python
def ensure_tag(remote, commit, tag, cwd, *, existing=None, timeout=PUSH_TIMEOUT)

Put tag on the mirror at commit. Returns what it did.

"present" when the mirror already carries the tag at exactly that commit, "pushed" when it was created. A tag standing at a DIFFERENT commit is a hard error: a released tag names what shipped, and moving one is never this module's decision.

existing is an already-read {tag: commit} map, so a caller materializing several tags reads the remote once.

#publish_release

python
def publish_release(pub, *, gh, repo, directory='.')

Create the mirror's Release for pub, or reconcile the existing one.

Returns "created", "reconciled" (the body gained or corrected its marker) or "already-correct".

#version_notes

python
def version_notes(changes_dir, version)

The version's generated changelog section, or "".

The per-version .md beside the JSONL is the release's own rendering of that version, which is exactly what the monorepo's Release carries -- so the mirror's Release says the same thing about the same version.

#publish_version

python
def publish_version(*, remote, root, subtree_path, version, tag, release_commit_sha, notes='', gh, existing_tags=None, directory='.', log=None)

Publish one released version onto the mirror: the tag, then the Release.

release_commit_sha is the release record's release commit -- the MONOREPO commit the version shipped from. The mirror's commit for it is derived here, and it is that commit the tag names and the Release's marker carries.

Returns (split_sha, tag_outcome, release_outcome). Raises :class:MirrorPublicationError on anything it cannot do; the caller decides how fatal that is (in the release flow, not very -- the primary release has already shipped and the mirror is a derived artifact).

Search