Skip to content

[Chore]: docs(release): add recovery playbook for missing-changeset merges #57

Description

@martyy-code

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:

  1. Identify that the workflow was a no-op (check gh api .../jobs for conclusion=skipped on Publish packages).
  2. 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.
  3. 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

Relevant Documentation

  • Existing: docs/internal/engineering/process/releasing-a-new-version.md
  • Plan: docs/internal/engineering/plans/release-system.md

Technical Approach

  1. Open a PR titled "docs: add recovery playbook for missing-changeset merges".
  2. In releasing-a-new-version.md, locate the "## Failure modes and recoveries" section.
  3. Append a new subsection with the recovery steps.
  4. 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

Metadata

Metadata

Assignees

No one assigned

    Labels

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions