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:

Check git status: Run git status to see if there's an active merge in progress
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

Strategy: Discard Pegasus migration changes, keep the user's changes
Reason: Migration files should be regenerated, not merged
Action: For conflicted migration files, accept theirs (the user's version from main), then run ./manage.py makemigrations after all conflicts are resolved
Git command: git checkout --theirs <migration-file> for each conflicted migration
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:

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)
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)
Check current branch: Run git status to see if they're already on the upgrade branch
Checkout the upgrade branch: If not already on it, run git checkout <pegasus-branch-name>
Pull latest changes: Run git pull to ensure the upgrade branch is up to date with the remote
Identify main branch: Determine the main development branch (usually main or master)
Run merge: Execute git merge <main-branch> to merge the main development branch into the Pegasus upgrade branch
Handle conflicts: Follow the conflict resolution strategies above
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, ask the user if they want to proceed with the post-merge steps or if they prefer to do them manually later.

If the user wants to proceed, run these steps:

Build assets: npm run build (or npm run dev for development)
Optional - Database migrations: Run ./manage.py makemigrations to create new migrations if needed
Optional - Run migrations: ./manage.py migrate to apply database changes
Optional - Run Tests: ./manage.py test to run the Python test suite
Optional - Docker users: They can run make upgrade instead of manual steps above
Push to GitHub: Run git push to push the merged changes to GitHub. Once pushed, the upgrade branch should be ready to merge into the main branch via pull request

If the user prefers to do these manually, inform them what steps they should take when ready.

Important reminders

Enable rerere: Suggest running git config rerere.enabled true to remember conflict resolutions for future upgrades
Never squash: When merging Pegasus PRs in GitHub, always use "Create a merge commit" (not squash or rebase)
Review changes: Always review what changed in the upgrade before committing
Always compare clean versions: When resolving non-trivial conflicts, use git show HEAD:<file> and git show main:<file> to see the clean versions from each branch, rather than trying to parse the conflict markers in place

Examples

Example 1: User has conflicts (most common)

User: "I have merge conflicts after upgrading Pegasus"
You: [Check git status, see conflicts in migrations and uv.lock]
You: "I can see you have conflicts in migrations and uv.lock. Let me help resolve these:
- For migrations: I'll keep your version and we'll regenerate them
- For uv.lock: I'll accept the Pegasus version and regenerate it
[Proceed to resolve conflicts]"

Example 2: User wants help with the merge

User: "Can you help me merge my changes into the Pegasus upgrade branch?"
You: "I can help with that. Let me:
1. Find the latest Pegasus upgrade branch
2. Check out that branch (or confirm you're already on it)
3. Merge your main development branch into it
4. Help resolve any conflicts that come up
[Proceed with finding branch and running git merge main]"

Edge cases

No pegasus upgrade branch: If the user doesn't have a pegasus-YYYY.MM branch, direct them to the Pegasus upgrade documentation
Too many conflicts: If there are dozens of conflicts across many files, suggest reviewing them in priority order (migrations first, then lock files, then configuration)
Custom modifications: Be conservative with user customizations - when in doubt, keep their changes and note what was different in Pegasus
Unfamiliar file types: If you encounter conflicts in files you're not sure how to handle, explain both sides of the conflict and ask the user which approach makes sense

djstripe 2.10 upgrade (Pegasus 2026.2.2+)

Pegasus 2026.2.2 upgraded djstripe from 2.9 to 2.10. This is a significant upgrade that requires extra steps beyond normal conflict resolution.

Migration squash

djstripe 2.10 squashed all previous migrations into 0001_initial and 0002_2_10. After resolving migration conflicts, check if any app migrations reference old djstripe migrations (e.g. ('djstripe', '0012_2_8')) that no longer exist. If so, update those dependencies to ('djstripe', '0001_initial'). Do NOT delete migrations — update their dependency references instead.

Fields moved to stripe_data

Many model fields were removed as DB columns and now read from the stripe_data JSONField via @property accessors. Key changes on Product: default_price, type are now properties. This means:

select_related("default_price") will fail — remove it, just use .get() directly
filter(), order_by(), values() on removed fields will fail — use stripe_data__<field> instead
Property access like product.default_price.id still works (it does a DB lookup from stripe_data)

Re-sync stripe data after migrating

After running ./manage.py migrate, run ./manage.py djstripe_sync_models Product Price to repopulate stripe_data for existing records. Without this, properties like product.default_price will return None because the old FK data isn't in stripe_data yet.

Obsolete workarounds

The RunSQL migration that altered djstripe_paymentintent.capture_method column length (workaround for dj-stripe#2038) is no longer needed. Clear its operations list (keep the migration file as a no-op for the dependency chain).