Adding missing documentation on how to resolve migration conflicts

[shmonks]

Dependency

• Information missing on how to resolve migration conflicts in GitHub and/or Django

Overview

We need to make it easy to:

• Record any missing documentation on how to resolve migration conflicts
• Keep those records in one place
• Create new issues based on those records

This issue is the place to record missing documentation and start creating related new issues.

Details

• We are striving to write documentation that helps developers use GitHub and Django.
• This issue tracks the documentation that needs to be added on how to resolve migration conflicts in GitHub and Django. If you've noticed missing documentation about other Git and/or Django processes,

see the following issues instead

• Add missing documentation to the PR review guide #419
• Add missing documentation on how to combine migrations in Django #421
• Add missing documentation on how to quickly checkout a PR #422
• Add missing documentation on how to add an alias in GitHub #423
• Add missing documentation on how to apply changes from one file to another in GitHub #425

Action Items

• For each piece of missing information, copy and paste the following template into a new comment below.

### Overview
We need to add [REPLACE WITH WHAT NEEDS ADDING], so that developers can [REPLACE WITH BENEFIT]

### Action Items
- [ ] [REPLACE WITH ACTION ITEMS]

### Resources/Instructions/Tags 

- 1.0x [REPLACE WITH LINKS TO ANY EXTERNAL DOCS THAT MIGHT BE USEFUL (WITH INSTRUCTIONS, IF NEEDED)]
- 1.0x [REPLACE WITH ANY RELEVANT TAGS e.g., git, django, etc.]

### Documentation Addition Notes
#### What's missing?
[REPLACE WITH DESCRIPTION OF WHAT'S MISSING FROM THE DOCUMENTATION]
   
#### Where should it go?
[REPLACE WITH URL OR INDICATE NEW PAGE AND PARENT PAGE]

####  When would this information have been useful?
[REPLACE WITH LINK TO THE PR/ISSUE/SITUATION THAT PROMPTED THE NEED FOR THIS CHANGE/ADDITION]
   
#### Which roles will benefit most from this information?
[REPLACE WITH ROLES]

• Fill out as many of the template's fields as possible.
• Copy and paste a link to your comment in Section 2: List of comments/issues about missing documentation on resolving migration conflicts below, using the next available number
• Copy the content of your comment
• Create a new issue, pasting the content of your comment into the new issue
• Add the following labels to the new issue
  • feature: docs: PD team documentation
  • size: 0.25pt
  • s: PD team
  • ready for dev lead
  • choose a complexity label that fits
  • choose the role label that fits
• When this new issue has been created, add a link to it in Section 2: List of comments/issues about missing documentation on resolving migration conflicts below. Make sure the link to your new issue appears beneath the link to your comment, so we can ensure that all comments get made into issues
• Hide the original comment (you can mark it 'Resolved')

Section 2: List of comments/issues about missing documentation on resolving migration conflicts

• 2.01 Missing Documentation on how to resolve migration conflicts in Github and Django #442

[shmonks]

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?

[REPLACE WITH URL OR INDICATE NEW PAGE AND PARENT PAGE]

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