You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
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
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)
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:
What specifically needs to happen:
Motivation / Why
This task is needed because:
In Scope
Out of Scope
User-Facing Impact
Component(s) Affected
Priority
p2: Medium - Normal priority
Estimated Effort
effort: xs - Few minutes
Related Issues / Pull Requests
Relevant Documentation
Technical Approach
Files that may need changes:
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