docs: How to combine migrations before merging a PR

[fyliu]

Dependencies

• 385

Overview

We need to add documentation for how to combine migrations before merging a PR for the benefit of developers so that they can refer to the guide as needed.

Action Items

• [ ] Add a page if this is a new topic
• [ ] Add documentation

Instructions

When doing PRs involving django models, sometimes the requested changes cause django to generate more migration files. To keep things simpler, it's recommended to combine migrations as much as possible at the end of the PR process so that there's one or very few migrations to merge. Follow these steps to merge all the PR migrations into one.

1. Check the new migrations created for the PR

   ls app/core/migrations/

   Let's say the PR created 0022-0027 in the core app

   ...
   Applying core.0020_rename_is_sponsor_sponsorpartner_is_org_partner_and_more... OK                                                                                                                                                            
   Applying core.0021_sdg... OK                                                                                                                                                                                                                 
   Applying core.0022_alter_sponsorpartner_table_affiliation_and_more... OK                                                                                                                                                                     
   Applying core.0023_rename_sponsorpartner_affiliate_and_more... OK                                                                                                                                                                            
   Applying core.0024_rename_is_sponsor_affiliation_affiliation_type... OK                                                                                                                                                                      
   Applying core.0025_remove_affiliation_affiliation_type_and_more... OK                                                                                                                                                                        
   Applying core.0026_alter_affiliation_created_at_alter_affiliate_table... OK                                                                                                                                                                  
   Applying core.0027_alter_affiliation_created_at... OK                                                                                                                                                                                        
   ...

2. Undo the migrations back to before the PR

   docker-compose exec web python manage.py migrate core 0021

3. Delete the migration files

   rm app/core/migrations/{0022*,0023*,0024*,0025*,0026*,0027*}

4. Reset the max_migration.txt back to before the PR branch (assuming that's the current upstream/main)

   git checkout upstream/main -- app/core/migrations/max_migration.txt

5. Generate the combined migration file and apply it

   docker-compose exec web python manage.py makemigrations
   docker-compose exec web python manage.py migrate

[shmonks]

Please provide update

1. Progress: "What is the current status of your project? What have you completed and what is left to do?"
2. Blockers: "Difficulties or errors encountered."
3. Availability: "How much time will you have this week to work on this issue?"
4. ETA: "When do you expect this issue to be completed?"
5. Pictures or links* (if necessary): "Add any pictures or links that will help illustrate what you are working on."

• remember to add links to the top of the issue if they are going to be needed again.

[dmartin4820]

Progress: Haven't started yet Blockers: None yet Availability: Weekend ETA: Over the weekend or early next week

10/16/2024 Update: Progress: Still haven't started yet. Thinking of dropping this task for now unless there's objections. Blockers: None yet Availability: Weekend ETA: N/A