Refs #27236 -- Added generic mechanism to handle the deprecation of migration operations.

4 files changed, 69 insertions, 9 deletions

diff --git a/docs/ref/checks.txt b/docs/ref/checks.txt
index 92278db659..55e4ca64b2 100644
--- a/docs/ref/checks.txt
+++ b/docs/ref/checks.txt
@@ -83,6 +83,7 @@ Django's system checks are organized using the following tags:
   you specify configured database aliases using the ``--database`` option when
   calling the :djadmin:`check` command.
 * ``files``: Checks files related configuration.
+* ``migrations``: Checks of migration operations.
 * ``models``: Checks of model, field, and manager definitions.
 * ``security``: Checks security related configuration.
 * ``signals``: Checks on signal declarations and handler registrations.
@@ -94,6 +95,10 @@ Django's system checks are organized using the following tags:
 
 Some checks may be registered with multiple tags.
 
+.. versionchanged:: 4.2
+
+    The ``migrations`` tag was added.
+
 Core system checks
 ==================
 
diff --git a/docs/releases/4.2.txt b/docs/releases/4.2.txt
index 34f8362be9..6282bfa580 100644
--- a/docs/releases/4.2.txt
+++ b/docs/releases/4.2.txt
@@ -169,7 +169,8 @@ Management Commands
 Migrations
 ~~~~~~~~~~
 
-* ...
+* The new :ref:`generic mechanism <migrations-removing-operation>` allows
+  handling the deprecation of migration operations.
 
 Models
 ~~~~~~
diff --git a/docs/topics/checks.txt b/docs/topics/checks.txt
index 9586466285..0864d6db38 100644
--- a/docs/topics/checks.txt
+++ b/docs/topics/checks.txt
@@ -128,18 +128,18 @@ The code below is equivalent to the code above::
 
 .. _field-checking:
 
-Field, model, manager, and database checks
-------------------------------------------
+Field, model, manager, migration, and database checks
+-----------------------------------------------------
 
 In some cases, you won't need to register your check function -- you can
 piggyback on an existing registration.
 
-Fields, models, model managers, and database backends all implement a
-``check()`` method that is already registered with the check framework. If you
-want to add extra checks, you can extend the implementation on the base class,
-perform any extra checks you need, and append any messages to those generated
-by the base class. It's recommended that you delegate each check to separate
-methods.
+Fields, models, model managers, migrations, and database backends all implement
+a ``check()`` method that is already registered with the check framework. If
+you want to add extra checks, you can extend the implementation on the base
+class, perform any extra checks you need, and append any messages to those
+generated by the base class. It's recommended that you delegate each check to
+separate methods.
 
 Consider an example where you are implementing a custom field named
 ``RangedIntegerField``. This field adds ``min`` and ``max`` arguments to the
@@ -194,6 +194,10 @@ the only difference is that the check is a classmethod, not an instance method::
             # ... your own checks ...
             return errors
 
+.. versionchanged:: 4.2
+
+    Migration checks were added.
+
 Writing tests
 -------------
 
diff --git a/docs/topics/migrations.txt b/docs/topics/migrations.txt
index cf3451a782..2350ac756c 100644
--- a/docs/topics/migrations.txt
+++ b/docs/topics/migrations.txt
@@ -503,6 +503,56 @@ database migrations such as ``__init__()``, ``deconstruct()``, and
 which reference the field exist. For example, after squashing migrations and
 removing the old ones, you should be able to remove the field completely.
 
+.. _migrations-removing-operation:
+
+Considerations when removing migration operations
+=================================================
+
+.. versionadded:: 4.2
+
+Removing custom operations from your project or third-party app will cause a
+problem if they are referenced in old migrations.
+
+To help with this situation, Django provides some operation attributes to
+assist with operation deprecation using the :doc:`system checks framework
+</topics/checks>`.
+
+Add the ``system_check_deprecated_details`` attribute to your operation similar
+to the following::
+
+    class MyCustomOperation(Operation):
+        system_check_deprecated_details = {
+            "msg": (
+                "MyCustomOperation has been deprecated. Support for it "
+                "(except in historical migrations) will be removed in "
+                "Django 5.1."
+            ),
+            "hint": "Use DifferentOperation instead.",  # optional
+            "id": "migrations.W900",  # pick a unique ID for your operation.
+        }
+
+After a deprecation period of your choosing (two or three feature releases for
+operations in Django itself), change the ``system_check_deprecated_details``
+attribute to ``system_check_removed_details`` and update the dictionary similar
+to::
+
+    class MyCustomOperation(Operation):
+        system_check_removed_details = {
+            "msg": (
+                "MyCustomOperation has been removed except for support in "
+                "historical migrations."
+            ),
+            "hint': "Use DifferentOperation instead.",
+            "id": "migrations.E900",  # pick a unique ID for your operation.
+        }
+
+You should keep the operation's methods that are required for it to operate in
+database migrations such as ``__init__()``, ``state_forwards()``,
+``database_forwards()``, and ``database_backwards()``. Keep this stub operation
+for as long as any migrations which reference the operation exist. For example,
+after squashing migrations and removing the old ones, you should be able to
+remove the operation completely.
+
 .. _data-migrations:
 
 Data Migrations