Missing Documentation on how to resolve migration conflicts in Github and Django

[vanessaavviles]

Overview

We need to add documentation, so that developers know how to resolve migration conflicts. For example, let's say you're rebasing and the max_migration.txt file shows a conflict. That's a sign that the numbered migration files are conflicting as well (because they're named differently, their conflicts don't show up in git).

Action Items

• Add content in the What's missing? section below to a new numbered item and linked page here: https://hackforla.github.io/peopledepot/contributing/howto/, editing or revising if necessary

Resources/Instructions/Tags

• 1.01 git, django

Documentation Addition Notes

What's missing?

In many cases, you can resolve migration conflicts by using the rebase_migration command provided by django-linear-migrations.

1. We're assuming you're at your branch and all migrations are applied.

2. Run this to rebase your branch to main:

   git rebase upstream/main

   note: for people that have rerere enabled, you can temporarily disable it by passing in this option: git -c rerere.enabled=false rebase ...

3. Now see if there's a conflict in core/migrations/max_migration.txt and note the lowest migration number. We're going to use this later.

4. If core/migrations/max_migration.txt does show a conflict (e.g., between core/0025 and core/0027), you'll need to undo the rebase. Run this:

   git rebase --abort

5. If previous migrations are part of the conflict, you'll need to roll the local database back to a point before them, so you can change those migrations if necessary. Run this to roll the database back to an earlier migration, before any of the migrations that are in conflict (replacing '0024' with the appropriate number):

   ./scripts/migrate.sh core 0024

6. Now re-run the rebase:

   git rebase upstream/main
   # see conflicts returned

7. Resolve code conflicts if any. (In case there's other conflicts besides the migrations)

8. Resolve the migration conflict:

   docker-compose exec web python manage.py rebase_migration core

9. Run all the migrations again to make sure the new ones apply cleanly:

   ./scripts/migrate.sh core

10. Stage all the fixes:

    git add <max_migration.txt> <changed migration files> <fixed code files if any>

11. Run pre-commit checks:

    pre-commit run

12. Finally, continue rebase:

    git rebase --continue

Where should it go?

When would this information have been useful?

• Create table project sdg xref 66 #385 for example, but this information is helpful for anyone who has created a PR and then wants to update it with latest changes from upstream/main

Which roles will benefit most from this information?

• Backend/ Dev