docs(release): establish the current preparation procedure - #389
Conversation
|
Warning Review limit reached
Next review available in: 4 minutes You've used all free OSS reviews for now. Wait for the free limit to reset to keep reviewing this public repository. How can I continue?After more reviews become available, a review can be triggered using the To avoid repeated limits, reduce automatic review volume by pausing incremental auto-reviews earlier, using label-based review opt-in, excluding WIP or generated PR titles, or requesting reviews manually when the PR is ready. If your team needs uninterrupted high-volume reviews, an organization admin can enable usage-based reviews. How do review limits work?CodeRabbit enforces per-developer PR review limits for each organization. Most developers receive the normal plan review availability. For paid Pro and Pro+ PR reviews, CodeRabbit uses adaptive limits for sustained high-volume activity. When a developer's recent PR review activity reaches the 95th percentile or higher among CodeRabbit users, additional reviews become available more gradually as earlier reviews age out of the rolling window. Please refer docs for additional details. Review details⚙️ Run configurationConfiguration used: Organization UI Review profile: ASSERTIVE Plan: Pro Plus Run ID: 📒 Files selected for processing (8)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
CI budget acknowledgementThe PR planner classified this as Splitting the release procedure, templates, promotion runbook, and agent routing would leave an intermediate branch with competing instructions and would run the default PR lanes more than once. Keeping them together produces one reviewable operating contract and one hosted proof cycle. No mutation/coverage claim is inferred from lanes that remain skipped. |
Measured release-implementation follow-upWhile verifying the procedure against the canonical source workflow, I found that #245 was closed without its remaining staging/finalization criteria being proven. It is now reopened with a concrete repair packet. The current source This documentation PR therefore states the correct release gate but does not claim the current workflow has earned it. A release remains blocked until #245 produces exact staged bytes, four-platform acceptance, diagnostics, and a terminal release-ready aggregate. |
EffortlessSteven
left a comment
EffortlessSteven
left a comment
There was a problem hiding this comment.
[P1] Bind tag creation to the approved release candidate SHA
Failure mode:
The Phase 4 commands pull whatever is currently at origin/main and then tag it, without consuming or asserting the release_source_commit recorded in the readiness ledger. A later source commit can therefore enter the tag after release-prep was reviewed; git status --short is also only displayed, not enforced as a clean-worktree guard.
Why here:
The same procedure requires an immutable exact-tag proof, but the command sequence does not establish that the tagged commit is the reviewed candidate.
Fix direction:
Record the full approved source SHA, fetch it explicitly, require a clean checkout, assert HEAD equals that SHA, verify the tag does not already exist, and create/verify the annotated tag against that exact object. Add a negative fixture for a source head that advances after readiness.
Validation:
A dirty checkout or advanced source main must fail before tag creation; the approved SHA must produce a tag whose peeled commit matches the readiness identity.
Confidence:
High.
[P1] Make the documented staged-candidate gate an actual blocking boundary
Failure mode:
The current source release workflow still lets release-binary-acceptance depend only on release-preflight and create-release, not upload-assets. The acceptance scripts download from the public releases/download URL, while the release is supposed to remain draft. There is also no terminal Release Candidate Ready aggregate that binds upload, validation, all four acceptance lanes, and release-mode tests into one fail-closed publication prerequisite.
Why here:
The procedure presents these jobs as the exact-tag gate, but issue #245 records that this implementation/proof is still unmet. An operator following the living procedure cannot obtain the claimed exact staged-candidate evidence from the current workflow.
Fix direction:
Either mark #245 as an explicit blocking prerequisite in this documentation PR, or implement the source-owned workflow in a separately authorized lane: stage one immutable candidate manifest, make every acceptance lane consume those exact staged bytes after upload, and add a terminal aggregate that gates publication. Preserve the negative broken-asset/checksum proof.
Validation:
A deliberately broken staged asset or checksum must make the terminal aggregate fail and leave the GitHub release non-current; a green run must identify one exact tag and candidate manifest.
Confidence:
High.
[P2] Remove trailing whitespace so the declared diff proof passes
Failure mode:
git diff --check swarm/main...HEAD fails on the new hard-break spaces in release-preparation.md and all three templates.
Why here:
The PR procedure explicitly requires git diff --check, so the current branch does not satisfy its own documented proof contract.
Fix direction:
Remove the trailing Markdown spaces or replace them with formatting that does not violate the repository whitespace gate, then rerun the exact diff check.
Validation:
git diff --check swarm/main...HEAD exits successfully on the exact PR head.
Confidence:
High.
Review boundary:
This is a read-only review of PR #389 at adffaef. The local declared xtask checks passed for docs, policy ledgers, goals, support tiers, workflows, file policy, automation authority, and promotion-state; the diff check did not.
Exact-head proofFinal head The PR remains draft for maintainer review. No promotion, version bump, tag, publication, or release-state mutation was performed. |
EffortlessSteven
left a comment
EffortlessSteven
left a comment
There was a problem hiding this comment.
[P1] Bind the documented tag to the approved readiness SHA
Failure mode:
The current exact head still documents git switch main, git pull --ff-only origin main, git status --short, and then git tag -a without consuming or asserting the readiness ledger's approved release_source_commit. A later source commit can therefore be tagged after the release candidate was reviewed, and a dirty checkout is only displayed rather than rejected.
Why here:
This procedure promises immutable exact-tag proof, but the documented operator path does not establish that the tag points at the reviewed source candidate.
Fix direction:
Require the full approved SHA as an input, fetch/resolve that object explicitly, require a clean tracked checkout, assert HEAD equals the approved SHA before tag creation, reject an existing tag, and verify the annotated tag peels to the approved commit. Add a negative example or fixture showing an advanced source head fails before tag creation.
Validation:
A dirty checkout and an advanced origin/main must fail before any tag operation; the approved SHA must produce a tag whose peeled commit matches the readiness identity.
Confidence:
High; inspected current PR head 23fdf206c8d567eace683db9c104fa2a465d3a2c, docs/release/release-preparation.md:297-301.
[P2] Make the declared whitespace proof pass
Failure mode:
git diff --check swarm/main...HEAD still reports trailing whitespace in the new hard-break lines in docs/release/release-preparation.md and all three release templates.
Why here:
The PR's expected proof explicitly includes git diff --check, so the current documentation branch does not satisfy its own acceptance command.
Fix direction:
Remove the trailing Markdown spaces or replace them with equivalent formatting that does not violate the repository whitespace gate.
Validation:
Run git diff --check swarm/main...HEAD on the exact PR head and require exit code 0.
Confidence:
High; reproduced against current 23fdf206 exact head.
Proof update — prior head supersededThe earlier exact-head comment for Current head: Routed |
|
@codex review Please review the current final head, especially the authority boundary that keeps version/changelog/shared candidate prep on swarm and limits source to release execution. |
![chatgpt-codex-connector[bot]](https://avatars.githubusercontent.com/in/1144995?s=60&v=4){kind=small}
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 5185ce973b
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
| procedure. Release decision, version bump, changelog freeze, tag, crates.io, | ||
| GitHub Release publication, signing, and package-channel work remain source | ||
| release-authority operations. |
There was a problem hiding this comment.
Failure mode: Following this handoff literally moves the release decision, version bump, and changelog freeze into shiplog after promotion, creating a second preparation lane and changing source away from the exact candidate proved on swarm before tagging. Why here: the canonical release procedure requires all three artifacts to be finalized on swarm and promoted together. Fix direction: classify only tagging, publication, signing, and package-channel execution as source-owned here, and state that candidate preparation precedes promotion. Validation: re-read both living procedures as one ordered sequence and confirm no step assigns shared candidate state to source. Confidence: high.
AGENTS.md reference: AGENTS.md:L43-L48
Useful? React with 👍 / 👎.
5185ce9 to
d03564d
Compare
|
Droid encountered an error —— View job Droid is reviewing code and running a security check… |
1 participant
Final exact-head proof
Current rebased head:
d03564d9508c39a1fe35cfa087b73117a276f1cbThis head is based on merged #391 (
ac9308542fc6ec4daa1337bf81303bcf443542e1) and observed locally:cargo xtask check-doc-artifacts— passcargo xtask check-policy-ledgers— passcargo xtask check-goals— passcargo xtask check-support-tiers— passcargo xtask check-workflows --mode blocking-allowlist— passcargo xtask check-file-policy --mode blocking-allowlist— passcargo xtask check-automation-authority --repository-role swarm— passcargo xtask promotion-state --check— passgit diff --check— passThe procedure now requires an approved full readiness SHA, clean tracked checkout, detached exact-SHA verification, existing-tag rejection, annotated-tag peel verification, and explicit stop conditions for source advancement or failed candidates. It states that #391 proves the swarm candidate contract while the source writer and exact-tag live proof remain required. No tag, source promotion, release, or publication was performed.
What changed Establishes one living release-preparation procedure and aligns the promotion and agent guidance with the control plane that now exists. - adds
docs/release/README.mdas the index separating current instructions from historical release receipts; - addsdocs/release/release-preparation.md, covering shared candidate definition/freeze on swarm, exact promotion, narrow source execution, immutable tagging, staged artifact proof, publication, closeout, rollback, and copyable checklists; - adds release decision, readiness-ledger, and execution-handoff templates; - rewrites the promotion runbook aroundcargo xtask promote, deterministic repeated dry-runs, idempotent source PR reuse, regular-merge verification, and bounded promotion closeout; - updatesAGENTS.mdand the source-of-truth taxonomy so future agents use the living procedures rather than old command transcripts. ## Why The historical0.xreadiness and handoff files are useful evidence but still contain release-specific tools and commands such as RTK-prefixed invocations. Meanwhile, the standing promotion runbook still taught a manual rawswarm/mainpush even though the repository has earned an exact-target, per-path, idempotent promotion planner/executor. That left two competing operating models: 1. the implemented fail-closedcargo xtask promotetransaction; and 2. copied historical/manual release and promotion commands. The authority boundary also needed to be explicit: version, lockfile, changelog freeze, README/guides, release decision, readiness ledger, and handoff skeleton are shared candidate state and therefore finish on swarm before promotion. Source owns only narrow release execution, tagging, publication, source-writer configuration, and public credentials. ## Procedure boundary The documented sequence is now: 1. define the user-facing release scope on swarm; 2. finish shared docs and behavior, then make the late version/lockfile/changelog freeze and prepare the versioned evidence skeletons on swarm; 3. prove the exact candidate with contributor, policy, package, and routed CI gates; 4. run two byte-identical current-head promotion dry-runs and inspect every exact path decision; 5. use the real idempotent command to create or reuse one source promotion PR; 6. regular-merge and verify the exact source checkpoint; 7. validate current source and merge only narrowly required source-owned release-writer changes; 8. tag one exact proven source commit; 9. keep one staged four-platform candidate set non-current while validation, first-use, negative controls, and the terminal readiness aggregate run; 10. publish crates.io and the GitHub release only after those exact-tag gates pass; and 11. record observed public evidence on swarm and promote that coherent release closeout back to source. A product/shared-documentation/version/package defect found on source returns to swarm. Historical mode, an older source ref, or a raw branch push is not an escape from a fail-closed current-head promotion result. ## Historical evidence Versioned release decisions/readiness ledgers and rootRELEASE_HANDOFF_*files are deliberately not bulk-rewritten. Existing files remain receipts for the commands and evidence actually used by those releases, not standing instructions for the next one. ## Review map -docs/release/release-preparation.md— living end-to-end release procedure and checklists. -docs/release/README.md— current-vs-historical documentation roles and authority boundary. -docs/release/templates/— bounded version-specific evidence templates. -plans/shiplog-swarm/promotion-runbook.md— canonical exact promotion transaction. -AGENTS.md,docs/README.md— routing and source-of-truth links. ## Expected proofbash cargo xtask check-doc-artifacts cargo xtask check-file-policy --mode blocking-allowlist cargo xtask check-goals cargo xtask check-support-tiers cargo xtask promotion-state --check git diff --checkThis connector-authored branch was inspected by exact base/head comparison. Hosted CI is the execution authority for the checks above. ## Claim boundary Documentation and operating-procedure change only. This PR does not prepare or merge a source promotion, change the current promotion manifest, bump a version, tag, publish to crates.io, create or publish a GitHub Release, sign artifacts, update package channels, or move release authority. ## Rollback Revert the squash merge. Historical release evidence and all source/swarm refs, policies, workflows, tags, packages, and release state remain untouched. Relates to #246.