mikkel/nexus
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
nexus/.planning/REBASE-RUNBOOK.md
Mikkel Georgsen 890cb52954 [nexus] docs(01-02): create zone taxonomy, rebase runbook, and hook installer 
- Add .planning/ZONE-TAXONOMY.md classifying all rename targets (DISPLAY/CODE/STORED)
- Add .planning/REBASE-RUNBOOK.md documenting range-diff rebase verification workflow
- Add scripts/install-hooks.sh for post-clone hook reinstallation
2026-04-04 03:55:41 +00:00

2.8 KiB
Raw Blame History

Nexus Rebase Runbook

Step-by-step workflow for rebasing Nexus fork commits onto new upstream Paperclip releases.

Prerequisites

  • git rerere enabled: git config rerere.enabled true
  • git range-diff available (git 2.19+, confirmed 2.39.5 on this machine)
  • Upstream remote configured: git remote add upstream https://github.com/paperclipai/paperclip.git (if not already)

Pre-Rebase Checklist

  1. Ensure working tree is clean: git status
  2. Fetch upstream: git fetch upstream
  3. Record current tip: git log --oneline -1 (save this SHA as OLD_TIP)
  4. Verify all tests pass before rebase: pnpm test:run

Rebase Procedure

# 1. Fetch latest upstream
git fetch upstream

# 2. Rebase nexus commits onto upstream/master
git rebase upstream/master

# 3. If conflicts arise:
#    - git rerere will auto-apply previously recorded resolutions
#    - For new conflicts: resolve manually, then `git add` + `git rebase --continue`
#    - rerere automatically records new resolutions for future use

# 4. Verify rebase integrity with range-diff
#    ORIG_HEAD is the pre-rebase tip (set automatically by git)
git range-diff upstream/master ORIG_HEAD HEAD

Post-Rebase Verification

  1. range-diff check: git range-diff upstream/master ORIG_HEAD HEAD
    • Every nexus commit should show as "equivalent" (minor offset changes only)
    • Flag any commit showing significant diff changes for manual review
  2. Test suite: pnpm test:run — all tests must pass
  3. Type check: pnpm typecheck (if available) or pnpm -r run typecheck
  4. Branding spot check: pnpm vitest run --project packages/branding

Handling Common Scenarios

Upstream changed a file we also changed (DISPLAY zone)

  • Most common: string changes in UI components
  • rerere should handle if previously resolved
  • If new: resolve keeping Nexus display string, git add, continue

Upstream added new constants to packages/shared/src/constants.ts

  • Our changes are in packages/branding/ (separate file) — no conflict expected
  • If AGENT_ROLE_LABELS format changes upstream, update the DISPLAY zone mapping

Upstream restructured a file entirely

  • range-diff will show the affected nexus commit as "changed"
  • Manually verify the nexus change still applies correctly
  • Update zone taxonomy if file paths changed

rerere Cache Notes

  • Cache lives in .git/rr-cache/ (not tracked by git)
  • Cache is machine-local — lost on re-clone
  • After a fresh clone, first rebase may require manual resolution
  • Subsequent rebases at the same conflict points will auto-resolve

Hook Re-installation

After a fresh clone, the commit-msg hook must be reinstalled:

# From repo root:
cp scripts/nexus-commit-msg-hook.sh .git/hooks/commit-msg
chmod +x .git/hooks/commit-msg

Or using the install script:

bash scripts/install-hooks.sh