Resolve Pegasus Conflicts

Resolve Pegasus Conflicts

Instructions

This skill helps users resolve merge conflicts when upgrading their SaaS Pegasus codebase. Most users will invoke this skill when they have merge conflicts after merging their main branch into a Pegasus upgrade branch, but you can also help run the merge process for them.

When invoked

First, determine what the user needs help with by checking their current state:

1. Check git status: Run git status to see if there's an active merge in progress
2. Ask the user: If unclear, ask whether they:
   • Already ran git merge and need help resolving conflicts (most common)
   • Want you to run the merge process for them
   • Need help understanding which conflicts to prioritize

If there's an active merge with conflicts

The user has already run git merge <main branch> and has conflicts to resolve. Help them resolve the conflicts using these strategies:

Database Migrations

Principle: When main/local and Pegasus disagree about a migration, main/local wins. Main's migration files typically reflect what the local DB (and prod) have already applied, so that history is the baseline you protect. When a Pegasus migration conflicts with or duplicates something main has already applied, you should drop Pegasus's version in favour of main's, then run ./manage.py makemigrations to re-express any genuine change as a clean forward diff (the change lives in the merged models, so makemigrations re-derives it).

• On a conflict: For conflicted migration files, accept the user's version from main with git checkout --theirs <migration-file>, then run ./manage.py makemigrations after all conflicts are resolved.
• Watch for silent (conflict-free) migration changes — this is easy to miss: Pegasus regenerates its own auto-generated migrations and sometimes renames them (e.g. 0002_customuser_language... → 0002_customuser_customer...). A rename is a delete-on-one-side + add-on-the-other, which git merges with no conflict markers — so it slips through silently and leaves you with a duplicate/competing migration the conflict step never flagged. After merging, always diff the migration dirs against main to catch this:

  git diff --name-status main HEAD -- '*/migrations/*.py'

  Treat any R (rename) the same as a conflict: restore main's file (git checkout main -- <file>), delete Pegasus's regenerated copy (git rm <file>), then ./manage.py makemigrations to regenerate the forward diff cleanly. Brand-new app migrations (all A, e.g. a freshly added ecommerce app) are fine — keep those as-is.
• djstripe migration references: If djstripe was upgraded, check if app migrations reference old djstripe migrations that no longer exist (see the "djstripe 2.10 upgrade" section below).

Dependency Lock Files (uv.lock, requirements.txt, package-lock.json)

• Strategy: Accept Pegasus changes to lock files, merge source files manually
• Source files: pyproject.toml, requirements.in, package.json
• Lock files: uv.lock, requirements.txt, package-lock.json
• Action:
  1. For source files: Merge carefully, keeping customizations
  2. For lock files: Accept ours (Pegasus version) with git checkout --ours <lock-file> and git add <lock-file>
  3. Immediately regenerate: Run uv sync (for uv.lock) or npm install (for package-lock.json) right after resolving to ensure dependencies are properly synced
• Important: Don't wait until post-merge steps - regenerate lock files immediately after resolving them

Static Assets (JavaScript/CSS bundles in static/)

• Strategy: Delete and regenerate
• Action: Accept either version (doesn't matter), will be rebuilt
• Regenerate: Run npm run build or npm run dev after merge

Configuration Files (.env.example, settings files)

• Strategy: Merge carefully, keep customizations
• Action: Review both sides and combine them intelligently

Other Files

• Strategy: Evaluate case-by-case
• Action: Read both versions, understand the changes, merge intelligently

If running the full merge process

If the user wants you to run the merge:

1. Fetch latest changes: Run git fetch to download the latest branches and commits from the remote (this ensures you can see the latest Pegasus upgrade branch)
2. Find the latest upgrade branch: Run git branch -a to list all branches and look for the latest Pegasus upgrade branch (usually prefixed with pegasus-YYYY.MM, e.g., pegasus-2025.01)
3. Check current branch: Run git status to see if they're already on the upgrade branch
4. Checkout the upgrade branch: If not already on it, run git checkout <pegasus-branch-name>
5. Pull latest changes: Run git pull to ensure the upgrade branch is up to date with the remote
6. Identify main branch: Determine the main development branch (usually main or master)
7. Run merge: Execute git merge <main-branch> to merge the main development branch into the Pegasus upgrade branch
8. Handle conflicts: Follow the conflict resolution strategies above
9. Dependency sync: Once conflicts have been resolved, you should re-sync dependencies.
   • Python: uv sync
   • JavaScript: npm install

Post-merge steps

After all conflicts are resolved and the merge is complete, run the verification steps below. By default, work straight through them without pausing for confirmation between steps — the user kicked off an upgrade and expects forward motion. Stop only if a step fails, or if the user has said they want to review before pushing.

1. Frontend install + build: npm install && npm run build
2. Python dependency sync: uv sync
3. Migrations: ./manage.py makemigrations then ./manage.py migrate. If migrate fails partway, see "Recovering from a partial migration" below.
4. Tests: ./manage.py test
5. Ruff format + lint: make ruff (auto-formats and auto-fixes lint issues)

Commit any pending changes produced by the steps above (e.g. new migrations, formatting fixes) with a clear message. Docker users can substitute make upgrade for the build/migrate steps.