[goosewobbler]

Summary

Docs disagreed with each other, and with the pipeline, about when commits and tags are pushed and how to recover.

• docs/architecture.md is now the single description: batch mode pushes only after every publish succeeds; per-package mode pushes the branch, then that package's tag, as each package succeeds; standing-PR mode already has the commit on main.
• Troubleshooting, the publish README, ci-setup, AGENTS.md, and the release-retry workflow link to that and no longer say to delete a tag whose version was published.
• The failure report and supersede warning say the same thing: re-run a batch or standing-PR publish, roll forward a per-package direct failure, and do not delete published tags. A roll-forward report leaves out the "Retrying is safe" note, since re-running that failure doesn't work.

Fixes #740.

Closes #735: #765 fixed items 1 and 2, and this settles item 3 the documented way, by rolling a per-package direct failure forward. Its remaining gaps moved to #774.

Known gap, out of scope here: when a direct release's branch push lands but a tag push fails, the report still recommends "Re-run failed jobs", which can't succeed. Tracked in #774.

Made with Cursor

Confidence Score: 4/5

The PR appears safe to merge, with non-blocking corrections needed in its recovery guidance.

Findings

1.  Report guesses what was pushed ▶
2.  Local retry can publish nothing ▶

Summary

The PR makes docs/architecture.md the shared description of publish order and recovery.

• Release guides explain when each mode pushes tags and how failures recover.
• Failure reports show recovery steps that match the publish mode.

Diagram

%%{init: {'theme': 'neutral'}}%%
flowchart TD
  A[Prepare files and local release tags] --> B{Publish mode}
  B -->|Batch| C[Publish all packages and verify]
  C --> D[Push branch, then tags]
  B -->|Per-package| E[Publish and verify one package]
  E --> F[Push its tag, then branch]
  F --> G{More packages?}
  G -->|Yes| E
  G -->|No| H[Finish remaining pushes]
  D --> I[Create GitHub Releases]
  H --> I
  J[Standing PR already merged] -. Skip branch pushes .-> D
  J -. Skip branch pushes .-> F

Loading

_{Reviews (1) · Last reviewed commit: "docs: describe publish order and partial..." · Reviewed by Greptile}

[goosewobbler]

@greptile review

[github-actions]

Standing release PR: #730 · v0.42.1 queued (4 packages) · open 7h 9m · ✅ ready to merge

Release Preview — v0.42.0 → v0.42.1

Note: Labels on this PR are advisory in standing-pr mode. Bumps come from conventional commits in the standing PR; override by editing labels on the standing PR itself. Add release:immediate to bypass the standing PR and release this PR directly.

These changes will be added to the release PR (#730) when merged:

Changelog

monorepo 0.42.0 → 0.42.1

Changed

• say that publishOrder turns off the crate dependency sort (rust) (PR #787)
• cover jsonOutput when disabled; fix inverted guard test (version) (PR #754 · closes #725)
• drop versionCalculator tests that mocked a missing helper (version) (PR #755 · closes #726)
• link standing-pr.yml comments to published ci-setup URLs (templates) (PR #756 · closes #728)
• base partial-failure recovery on what was actually pushed
• describe publish order and partial-failure recovery by mode

Fixed

• leave the retry note off a roll-forward failure report (release)
• keep dependency order and branch-first push in per-package mode (publish) (PR #765)
• report publish PipelineError partial output in --json (release) (PR #760)
• report merge without publish as changed (release) (PR #748 · closes #724)
• resolve relative --project-dir before loading config (version) (PR #757 · closes #698)
• untagged-package warning matches resolved changelog range (version) (PR #749 · closes #727)
• commit the standing PR's release branch with the PR title (release) (PR #729)
• keep root changelog history when several packages release (notes) (PR #775 · closes #736)
• keep the failure report's state and recovery consistent (release)

All packages → 0.42.1 (sync versioning)

• @releasekit/version
• @releasekit/notes
• @releasekit/publish
• @releasekit/release

After merge — predicted release

No version escalation — this PR's changes will be included in the queued release without affecting the projected versions.

Package	Standing PR	This PR	After merge
monorepo	0.42.1	0.42.1	0.42.1

---

Updated automatically by ReleaseKit

[goosewobbler]

@greptile review