docs: runbook for Raft Artifacts mirror publication - #145
Merged
Conversation
bytemain
force-pushed
the
bisheng/raft-artifacts-runbook
branch
2 times, most recently
from
August 19, 2026 05:59
8bb69d1 to
af9f4c7
Compare
artin asked that the publication process land in the repo so the next one is easier. Tasks #120/#121/#127/#141 each grew a near-duplicate workflow and the knowledge stayed in threads. Captures the traps that actually cost rounds, rather than restating the happy path: the authority serves no directory listing and answers a directory URL with 200 plus a not-browseable notice rather than 404; Raft answers some absent paths with 401 so 404 is not the only absent signal; Raft serves no maven-metadata.xml so only exact versions resolve; carriers must be exactly one commit or identity-diff fails; and expected_sha must be the landed staging3 tip, because squash-merging means the reviewed head is not on staging3. Two enumeration habits are recorded as actions rather than maxims: keep the probe grid in the manifest header so the next coordinate runs a known grid, and pair every zero-hit claim with a known-present positive control, since a bare zero cannot distinguish absence from a filter aimed at the wrong thing. Adds stage_manifest.py, which materialises a frozen manifest into a local Maven layout with per-byte verification so a consumer can be exercised before an unyankable write. It deliberately ships no consumer-side version check. Such a check reads a build file this repository does not own, so it could not run here; shipping it would imply coverage that does not exist. The consumer contract belongs to the consuming repository, and the runbook says so. The 1.7.3 trap is documented with measurements rather than speculation: kotlinx-coroutines-test:1.7.3 is absent from Tencent and Raft but present on Maven Central, while kotlinx-coroutines-test-ohosarm64:1.7.3 exists nowhere at all, because upstream never published an OHOS target. Copying that version therefore fails loudly at variant resolution instead of silently falling back. Every stage_manifest failure path is covered by tests that go red when the exception type is removed. Without them the first draft shipped five raise sites referencing an undefined name, so the tool would have reported itself as broken at the exact moment it caught a real digest mismatch. Suite is 24/24. Signed-off-by: BiSheng <raft-mobile-bisheng@mail.build>
bytemain
force-pushed
the
bisheng/raft-artifacts-runbook
branch
from
August 19, 2026 06:06
af9f4c7 to
0469c59
Compare
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
@artin asked that the publication process land in the repo so the next mirror is
easier. Tasks #120/#121/#127/#141 each grew a near-duplicate workflow, and the
knowledge that actually matters stayed in chat threads.
Small and self-contained: one document plus one script and its tests. No
workflow, manifest or publication-critical code is touched, so it cannot
affect any existing receipt.
tools/raft-artifacts/RUNBOOK.mdWritten around the traps that cost real CI rounds, not the happy path:
200 with a not-browseable notice, not 404 — a check treating "no listing"
as 404 reads the wrong signal. The file set is derived from module metadata
and then probed, so record the probe grid: task ci: pin Kuikly writer control plane #141's first inventory
used a narrow grid and silently missed 5 files.
maven-metadata.xml, so exact versions only: no ranges, nolatest, no SNAPSHOT.identity-difffails even wheneverything else is green.
expected_shamust be the landedstaging3tip. Squash-merging changesthe SHA, so the reviewed PR head is not on
staging3and fails closed.contract-bound data rather than prose.
for that platform only — a known limitation to state, not discover.
tools/raft-artifacts/task141_gate_support.pyThis existed only on a throwaway gate branch that has since been deleted, so it
was about to be lost. Two commands:
stage— materialise a frozen manifest into a local Maven layout, verifyingevery byte, to test a consumer before publishing anything.
ohos-test-contract— guards the 1.7.3 trap. Mobile's OHOS leg pinskotlinx-coroutines-core:1.8.0-KBA-002, while the non-OHOS build file pins1.7.3; copying that version across legs requests a coordinate mirrorednowhere and absent from Raft. Exempt while the coordinate is absent, strict
once present.
Scope honesty: that guard reads a build file, so it enforces nothing until
wired into the CI of the repository that owns that file. The runbook says this
explicitly instead of implying this repo covers Mobile.
Suite is 23/23.