Coordinated Multi-PR Workflow

This workflow runs two PRs in lockstep — one in ux-prototype (publishing previews), one in the consumer (consuming them). Both PRs gate on their own full CI suite. It is heavier than a plain preview publish (which assumes loose coupling) and cleaner than local side-by-side (which has no CI fidelity).

When to use

• The change is genuinely cross-repo: the design-system change and the consumer change form a single logical unit and must merge in coordination.
• Both PRs must pass their own CI before either is mergeable.
• You want a clear, reviewable record of the contract change in both repos.

Sequence

Phase 1 — Initial publication

1. ux-prototype dev opens a PR with a pre-release CHANGELOG entry (e.g. 4.12.0-alice-FD42). On push, publish-preview.yml publishes @arda-cards/design-system@4.12.0-alice-FD42-1 with dist-tag alice-FD42.
2. Consumer dev opens a PR that:
   • Bumps package.json to depend on the preview: npm install @arda-cards/design-system@alice-FD42.
   • Implements the consumer-side changes that exercise the new design-system capability.
3. Both PRs are linked to each other in their descriptions (“Depends on / blocks: …”).

Phase 2 — Iteration

4. As ux-prototype dev pushes new commits, each push republishes (UID increments). The dist-tag advances.
5. Consumer dev pulls latest by re-running npm install @arda-cards/design-system@alice-FD42 and commits the updated lockfile to the consumer PR.
6. Both PRs run their own CI on every push. CI failures on either side surface real integration issues.

Phase 3 — Convergence

7. When both PRs are review-ready and CI is green:
   • ux-prototype dev swaps the changelog entry from pre-release (4.12.0-alice-FD42) to stable (4.12.0). validate-release switches from failing to passing.
   • On push, publish-preview.yml correctly skips the publish (status no longer prereleased).
8. ux-prototype PR merges first. publish.yml ships stable @arda-cards/design-system@4.12.0 with dist-tag latest.
9. Consumer dev swaps the consumer PR’s dependency from the preview to stable: npm install @arda-cards/design-system@4.12.0 (or @latest).
10. Consumer PR merges second, now using a stable, published, immutable artifact.

Phase 4 — Cleanup

11. The next nightly run of cleanup-preview.yml marks the 4.12.0-alice-FD42-* previews as obsolete (because stable 4.12.0 exists) and deletes them after the 24h grace period.

Contracts

• Merge order is non-negotiable: design-system PR ships stable first, consumer PR bumps to stable, consumer PR merges. The reverse breaks consumers transiently.
• Consumer PR cannot merge with a preview dependency. Before final approval, swap to stable. (If the consumer uses dependabot or similar tooling, they may need to silence it during the preview window.)
• Both PRs have their own validation. The consumer’s CI should be capable of failing the PR if integration with the preview is broken.
• Cleanup cannot run during the convergence window. It can — and that’s fine, as long as you don’t merge the consumer PR pointing at a pre-stable preview. The cleanup workflow only purges preview versions whose stable base has shipped, so the convergence sequence is safe by construction (preview is purged only after stable exists, by which point consumer should have swapped).

Trade-offs

Pro	Con
Highest CI fidelity for cross-repo changes	Highest coordination overhead — two PRs to keep in sync
Real publish artifact tested by real consumer CI	Consumer PR’s package-lock.json churns on every preview iteration
Clear, reviewable record in both repos	Convergence sequence requires manual discipline
Bugs surface in consumer CI before stable ships	Lockfile must be re-bumped to stable before consumer merge

Edge cases

• Reviewer bandwidth mismatch. If the design-system PR is approved but the consumer PR isn’t, the design-system PR can still merge as stable; the consumer PR then bumps to stable when ready. Effectively this degrades into canonical release.
• Design-system PR rejected after preview adoption. The consumer PR’s CI was passing against a preview that’s now obsolete. Two options: rework the design-system PR (preview series continues), or close the consumer PR and revert to the previous stable.
• Multiple consumers depend on the same preview. Each consumer PR is an independent integration test. The design-system dev gets parallel signal from each. Treat conflicting feedback as a design discussion.

Related

• Preview publish — the lighter-weight version when consumer-side gating isn’t required
• Cleanup contract — when previews disappear
• Canonical release — the fallback if coordination breaks down