PR Merge Boundary Validation Runbook

Validate chained pull requests at each merge boundary with explicit checks, stale-approval handling, and rollback awareness.

devops

Quality

👁️0 views

docs

>Payload Data

Editable Format

# PR Merge Boundary Validation Runbook

Imported from curated first-party documentation sources.

## What this covers
Use this runbook when a merge sequence spans dependent pull requests and each boundary needs fresh validation.

## Use this when
- Managing dependency-chained pull requests
- Refreshing stale approvals near merge time
- Reducing merge surprises through checkpoint validation

## Expected outcomes
- Each merge boundary has a concrete verification step
- Review freshness stays visible as branches evolve
- Rollback planning is captured before the merge happens

## Source synthesis
- EVOKORE-MCP/docs/PR_MERGE_RUNBOOK.md (https://github.com/mattmre/EVOKORE-MCP/blob/main/docs/PR_MERGE_RUNBOOK.md)

## Dedupe notes
Keeps the merge-boundary validation concept separate from more general workflow or orchestration docs.

## Source excerpts

### EVOKORE-MCP/docs/PR_MERGE_RUNBOOK.md
Operator runbook for reliable merges and context-rot prevention.

## Pre-merge Checklist

- [ ] PR scope matches approved plan
- [ ] PR description is filled using `.github/PULL_REQUEST_TEMPLATE.md`
- [ ] PR metadata automation check (`scripts/validate-pr-metadata.js`) is passing for pull_request CI runs
- [ ] Required tests pass locally/CI
- [ ] Docs updated for user-facing behavior changes
- [ ] Release-impacting changes called out
- [ ] Follow-up issues captured (if any)

## Required Checks by Change Type

Use this as the minimum check set before approval and merge:

| Change type | Required checks |
| --- | --- |
| Docs-only changes | `node test-docs-canonical-links.js` |
| Ops/docs process changes (`docs/PR_MERGE_RUNBOOK.md`, `next-session.md`, orchestration docs) | `node test-ops-docs-validation.js` and `node test-docs-canonical-links.js` |
| Source/tooling/config changes (`src/`, `scripts/`, workflow/config files) | Relevant targeted tests for touched area plus CI-required suite |
| Release-flow changes | `node test-npm-release-flow-validation.js` plus docs/link checks |

If a PR spans multiple change types, run the union of required checks.

## Reviewer Responsibilities

- Confirm PR scope and dependency assumptions are explicit in description.
- Confirm PR metadata fields from `.github/PULL_REQUEST_TEMPLATE.md` are complete.
- Verify required checks for each change type are attached in PR evidence.
- Block approval if dependency base PR is not merged or branch is stale.
- Approve only the current chain head; do not pre-approve non-head dependent PRs.
- Confirm all review conversations are resolved before final approval.
- Ensure merge strategy and rollback notes are documented for risky changes.

## Merge Steps

1. Rebase or update branch with latest target branch.
2. Re-run required validations.
3. Confirm reviewer approvals and resolved conversations.
4. Merge via approved strategy.
5. Record merge commit/PR number in tracker.

## Merge-boundary Checkpoints

At every dependency merge boundary (`base -> dependent`):

1. Rebase dependent PR branch on latest `main` immediately after parent merge.
2. Re-run required checks and attach updated evidence in PR metadata.
3. Revalidate approvals for the new head state (stale approvals must be refreshed).
4. Confirm merge-boundary revalidation notes are updated before merge.

## Merge-order Controls (Dependency Chain)

1. Define merge order explicitly in PR descriptions (`base -> dependent`).
2. Merge only the current chain head; hold dependents until parent merge is complete.
3. After each merge, rebase
...

Source

https://github.com/mattmre/EVOKORE-MCP/blob/main/docs/PR_MERGE_RUNBOOK.md

SIMILAR_PROMPTS

SCANNING_SIMILARITY...