Add documentation for plugins datamigration

docs/how_to/custom_plugins.rst

@@ -755,3 +755,51 @@ Example::
                 alias.alias_placeholder = placeholder
             alias.save()
             return HttpResponse("ok")
+
+
+.. _plugin-datamigrations-3.1:
+
+Plugin data migrations
+======================
+
+Due to the migration from mptt to treebeard in version 3.1, the plugin model is different between
+the two versions. Schema migration are not affected as the migration systems (both South and
+Django) detects the different bases.
+
+Data migration are a different story, though.
+
+If your datamigration does something like:
+
+.. code-block:: django
+
+    MyPlugin = apps.get_model('my_app', 'MyPlugin')
+
+    for plugin in MyPlugin.objects.all():
+        ... do something ...
+
+You may end up with an error like
+``django.db.utils.OperationalError: (1054, "Unknown column 'cms_cmsplugin.level' in 'field list'")``
+because depending on the order the migrations are executed, the historical models may be out of
+sync with the applied database schema.
+
+To keep compatibility with 3.0 and 3.x you can force the datamigration to run before the django CMS
+migration that creates treebeard fields, by doing this the datamigration will always be executed
+on the "old" database schema and no conflict will exist.
+
+For South migrations add this:
+
+.. code-block:: django
+
+    needed_by = [
+        ('cms', '0070_auto__add_field_cmsplugin_path__add_field_cmsplugin_depth__add_field_c')
+    ]
+
+
+For Django migrations add this:
+
+.. code-block:: django
+
+    run_before = [
+        ('cms', '0004_auto_20140924_1038')
+    ]
+

docs/upgrade/3.1.rst

@@ -41,7 +41,7 @@ Other than this, end users should not notice any changes.
 
 .. note:: User feedback required
 
-    We require as much feedback as possible about the performance of django-treebeard in this 
+    We require as much feedback as possible about the performance of django-treebeard in this
     release. Please let us know your experiences with it, especially if you encounter any problems.
 
 .. note:: Backward incompatible change
@@ -52,6 +52,11 @@ Other than this, end users should not notice any changes.
     documentation <https://tabo.pe/projects/django-treebeard/docs/2.0/>`_ for information
     on how to use equivalent calls in ``django-treebeard``.
 
+.. note:: Handling plugin data migrations
+
+    Please check :ref:`plugin-datamigrations-3.1` for information on how to create
+    migrations compatible with django CMS 3.0 and 3.1
+
 
 Action required
 ---------------
@@ -140,7 +145,7 @@ queries that are generated, in order to make it faster.
 
 .. note:: User feedback required
 
-    We require as much feedback as possible about the performance of this feature in this 
+    We require as much feedback as possible about the performance of this feature in this
     release. Please let us know your experiences with it, especially if you encounter any problems.
 
 Toolbar API extension