[docs] How to combine migrations before merging a PR

[fyliu]

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