Repository navigation
[Chore]: docs(release): add recovery playbook for missing-changeset merges #57
Description
Task Description
Add a recovery playbook to docs/internal/engineering/process/releasing-a-new-version.md covering the case where a release PR has been merged into main without any .changeset/*.md in the diff.
The current document (section 3 "Confirm the changeset count") only says "do NOT merge the PR" - it does not cover what to do once the merge has happened. The playbook should document the recovery procedure that was used during the 1.3.0 release:
- Identify that the workflow was a no-op (check gh api .../jobs for conclusion=skipped on Publish packages).
- Decide whether to keep the planned version or accept a re-bump:
- Keep the planned version: revert the merge, recreate release/vX.Y.Z from main, leave .changeset/*.md files uncommitted, re-merge.
- Accept a re-bump: add a .changeset/release-vX.Y.Z.md with patch bump on a new commit on main, push, trigger workflow_dispatch with dry_run=false. The result is X.Y.Z+1 instead of the planned X.Y.Z.
- Verify the artifacts (git ls-remote --tags, gh release view) after the recovery.
What specifically needs to happen:
- Add a "Failure modes and recoveries" subsection covering the "merged without changesets" case.
- Cross-reference the companion issues on workflow signaling and manual-bump detection.
- Update the workflow contract recap to mention that an explicit workflow_dispatch is the canonical recovery trigger.
Motivation / Why
This task is needed because:
- The runbook is silent on a failure mode that has already happened once (PR chore(release): 1.3.0 #52 -# 1.3.0).
- Without a documented recovery path, every release engineer will re-derive the procedure from scratch (~20 minutes of investigation the first time).
- Documenting the trade-off (planned version vs. re-bump) up front makes the decision explicit and reversible.
In Scope
- Add a new subsection "Merged without a changeset" under "Failure modes and recoveries".
- Update the "Workflow contract recap" to mention workflow_dispatch as the explicit recovery trigger.
- Add a short "Recovery decision matrix" table: keep version vs. accept re-bump.
Out of Scope
- Modifying .github/workflows/release.yml (covered by the companion refactor issue).
- Changing the release branching model.
- Adding tests - this is a documentation-only task.
User-Facing Impact
- No user-facing impact - internal/tooling/maintenance only
Component(s) Affected
- Documentation
Priority
p2: Medium - Normal priority
Estimated Effort
effort: xs - Few minutes
Related Issues / Pull Requests
- Related PR: chore(release): 1.3.0 #52, fix(release): remove unsupported --packages flag from changeset publish #53.
- Companion issues: [BUG] release: workflow reports success on no-op when no changeset in merge #55 (bug, no-op workflow), [Refactor]: release: detect manual version bumps as a publish trigger #56 (refactor, manual-bump detection).
Relevant Documentation
- Existing: docs/internal/engineering/process/releasing-a-new-version.md
- Plan: docs/internal/engineering/plans/release-system.md
Technical Approach
- Open a PR titled "docs: add recovery playbook for missing-changeset merges".
- In releasing-a-new-version.md, locate the "## Failure modes and recoveries" section.
- Append a new subsection with the recovery steps.
- In the "## Workflow contract recap" section, add a sentence noting that explicit recovery uses workflow_dispatch.
Files that may need changes:
- docs/internal/engineering/process/releasing-a-new-version.md
Risk Assessment
Risk: documentation drift if the companion issues (#55, #56) land first and change the procedure.
Mitigation: use cross-references, not duplicated prose.
Rollback plan: revert the PR.
Pre-Submission Checklist
- Task description clearly defines the end state
- Scope (in/out) is clearly defined
- Component(s) affected are specified
- Searched for existing issues covering this work
- Dependencies identified (companion issues filed in same session)
- Will be labeled according to project taxonomy
Activity