Mikkel Georgsen
3a76d5f972
- 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
83 lines
2.8 KiB
Markdown
83 lines
2.8 KiB
Markdown
# 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
|
|
|
|
```bash
|
|
# 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:
|
|
|
|
```bash
|
|
# 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
|
|
bash scripts/install-hooks.sh
|
|
```
|