try to improve the model deletion docs

Author: wedamija

develop-docs/api-server/application-domains/database-migrations/index.mdx

@@ -252,7 +252,7 @@ Extra care is needed here if the table is referenced as a foreign key in other t
     - Remove any database level foreign key constraints from this table to other tables by setting `db_constraint=False` on the columns.
     - Remove the model and in the generated migration use `SafeDeleteModel(..., deletion_action=DeletionAction.MOVE_TO_PENDING)` to replace `DeleteModel(...)`. This only marks the state for the model as removed.
 - Deploy. It's important that all previous pull requests are in production before we remove the actual table.
-- Make a pull request that create a new migration that has the same `SafeDeleteModel` operation as before, but set `deletion_action=DeletionAction.DELETE` instead. This deletes the actual table from Postgres.
+- Make a pull request that creates a new migration that has the same `SafeDeleteModel` operation as before, but set `deletion_action=DeletionAction.DELETE` instead. This deletes the actual table from Postgres.
 - Deploy
 
 Here's an example of removing this model:
@@ -272,14 +272,56 @@ class TestModel(Model):
 
 First, we remove all references to this model from the codebase, including making sure that it's not referenced by any other models. This is best done as a separate pr to keep things clean.
 
-Next we need to remove any db level foreign key constraints. To do this, we change this column and generate a migration:
+Next we produce two migrations, in individual prs that we will deploy separately.
 
+First PR
 ```python
-project = FlexibleForeignKey("sentry.Project", db_constraint=False)
+# <Model removed from code completely>
+
+# First migration
+# ... Migration boilerplate ...
+operations = [
+    migrations.AlterField(
+        model_name="testmodel",
+        name="project",
+        field=sentry.db.models.fields.foreignkey.FlexibleForeignKey(
+            db_constraint=False,
+            on_delete=django.db.models.deletion.CASCADE,
+            to="sentry.project",
+        ),
+    ),
+    SafeDeleteModel(name="TestModel", deletion_action=DeletionAction.MOVE_TO_PENDING),
+]
+# ... Migration boilerplate ...
+```
+
+Second PR:
+```python
+# Second migration
+# ... Migration boilerplate ...
+operations = [
+    SafeDeleteModel(name="TestModel", deletion_action=DeletionAction.DELETE),
+]
+# ... Migration boilerplate ...
 ```
 
-The operations in the migration look like
+So once we have these two prs, we merge/deploy the first, and then the second and then the table is fully removed.
+
+So to recap the steps here:
+ - Remove all references to the model in the code in a separate pull request and merge. Doesn't matter if this deploys before the next step or not.
+ - Remove any foreign key constraints and delete the model using `SafeDeleteModel(..., deletion_action=DeletionAction.MOVE_TO_PENDING)`. These operations can be in the same migration to save time.
+ - Deploy all previous before continuing.
+ - Remove the table from Postgres using `SafeDeleteModel(..., deletion_action=DeletionAction.DELETE),`
+
+If you're comfortable producing these prs and deploying them, then stop here. Otherwise, this next section covers how to produce them in more detail.
+
+To produce the first migration, we need to remove any db level foreign key constraints and remove the table from the codebase. To remove the db level foreign key constraints we add `db_constraint` to this column and generate a migration:
 
+```python
+project = FlexibleForeignKey("sentry.Project", db_constraint=False)
+```
+
+This produces a migration with operations like:
 ```python
 operations = [
     migrations.AlterField(
@@ -294,23 +336,23 @@ operations = [
 ]
 ```
 
-Once we've done this, we can now remove the model from code and generate the migration to remove it. The generated migration looks like this:
+Next, we remove the model from code and generate the migration to remove it. The generated migration looks like this:
 
 ```python
 operations = [
     migrations.DeleteModel(name="TestModel"),
 ]
 ```
 
-Deleting this way is unsafe, so we want to replace this with `SafeDeleteModel` instead. So this becomes
+Django doesn't know about the `SafeDeleteModel` operation, so we replace it with that instead. This allows us to remove all state related to the model, but defer deleting it until a later migration. So this becomes
 
 ```python
 operations = [
     SafeDeleteModel(name="TestModel", deletion_action=DeletionAction.MOVE_TO_PENDING),
 ]
 ```
 
-Using `SafeDeleteModel` allows us to remove all the state related to the model, but defer deleting it until a later migration. So now, we can combine the migration to remove the constraints and delete the model state together like so
+So now as a final step, we can combine these operations into a single migration, which is the first migration we want to deploy.
 ```python
 operations = [
     migrations.AlterField(
@@ -326,21 +368,15 @@ operations = [
 ]
 ```
 
-So now we deploy this migration and move onto the final step.
-
-In this last step, we will use `SafeDeleteModel` again to finally remove the table from Postgres. First, we generate an empty migration using `sentry django makemigrations <your_app> --empty` to produce an empty migration, and then modify the operations to be like:
+To produce the second migration we generate an empty migration (`sentry django makemigrations <your_app> --empty`), then use the same `SafeDeleteModel` command from the previous migration, but change the deletion_action to `DeletionAction.DELETE`. This operation will remove the table from Postgres:
 
 ```python
 operations = [
     SafeDeleteModel(name="TestModel", deletion_action=DeletionAction.DELETE),
 ]
 ```
 
-Then we deploy this and we're done. So to recap the steps here:
- - Remove all references to the model in the code in a separate pull request and merge. Doesn't matter if this deploys before the next step or not.
- - Remove any foreign key constraints and delete the model using `SafeDeleteModel(..., deletion_action=DeletionAction.MOVE_TO_PENDING)`. These operations can be in the same migration to save time.
- - Deploy all previous before continuing.
- - Remove the table from Postgres using `SafeDeleteModel(..., deletion_action=DeletionAction.DELETE),`
+This second PR will contain only the migration and related boilerplate.
 
 ### Foreign Keys