Merge 6d6b68d into 85f17ca

docs/upgrade/3.1.rst

@@ -14,7 +14,8 @@ possible.
 .. warning:: Upgrading from previous versions
 
     3.1 introduces some changes that **require** action if you are upgrading
-    from a previous version. Please read :ref:`upgrade-guide-3.1`.
+    from a previous version. Please read :ref:`upgrade-guide-3.1` for a step-by-step guide to the
+    process of upgrading from 3.0 to 3.1.
 
 *****************
 What's new in 3.1
@@ -46,9 +47,10 @@ Other than this, end users should not notice any changes.
 .. note:: Backward incompatible change
 
     While most of the low-level interface is very similar between ``django-mptt`` and
-    ``django-treebeard`` they are not exactly the same.
-    If any custom code interfaces with plugins and pages tree low level interface, please check
-    the ``django-treebeard`` documentation for the updated interface.
+    ``django-treebeard`` they are not exactly the same. If any custom code needs to make use of the
+    low-level interfaces of the page or plugins tree, please see the `django-treebeard
+    documentation <https://django-treebeard.googlecode.com/svn/docs/index.html>`_ for information
+    on how to use equivalent calls in ``django-treebeard``.
 
 
 Action required
@@ -169,52 +171,61 @@ Some user interfaces have some plugins hidden from display in edit/preview mode.
 :ttag:`render_plugin_block` provides a way to expose them for editing, and also more generally
 provides an alternative means of triggering a plugin's change form.
 
-
-Remove deprecations
+Plugin table naming
 ===================
 
-* ``cms.context_processor.media`` has been removed in favor of
-  ``cms.context_processor.cms_settings``, update your settings accordingly;
+Old-style plugin table names (for example, ``cmsplugin_<plugin name>`` are no longer
+supported. Relevant code has been removed.
 
-* Old-style plugin table names are no longer supported. Relevant code has been removed; any
-  plugin table name must be migrated to the standard table names layout;
+Action required
+---------------
 
+Any plugin table name must be migrated to the standard (``<application name>_<table name>`` layout.
 
-.. _upgrade-guide-3.1:
+``cms.context_processor.media`` replaced by ``cms.context_processor.cms_settings``
+==================================================================================
 
-***********************************
-Upgrading for django CMS 3.0 to 3.1
-***********************************
+Action required
+---------------
 
-The two major changes regarding 3.1 are the removal of django-mptt in favor of django-treebeard
-and the dropped support for Django prior 1.6.
+Replace the ``cms.context_processor.media`` with ``cms.context_processor.cms_settings`` in
+``settings.py``.
+
+
+.. _upgrade-guide-3.1:
+
+*******************************
+Upgrading django CMS 3.0 to 3.1
+*******************************
 
 Preliminary steps
 =================
 
-Before upgrading, please make sure that you current database is consistent.
+Before upgrading, please make sure that your current database is consistent and in a healthy state.
 
 To ensure this, run two commands:
 
 * ``python manage.py cms delete_orphaned_plugins``
 * ``python manage.py fix_mptt``
 
+**Make a copy of the database before proceeding further.**
+
 Settings update
 ===============
 
-* Change ``cms.context_processor.media`` in ``cms.context_processor.cms_settings`` in
-  ``TEMPLATE_CONTEXT_PROCESSORS``;
-* Add ``treebeard`` in ``INSTALLED_APPS`` and remove ``mptt`` if not required by other
-  applications;
+* Change ``cms.context_processor.media`` to ``cms.context_processor.cms_settings`` in
+  ``TEMPLATE_CONTEXT_PROCESSORS``.
+* Add ``treebeard`` to ``INSTALLED_APPS``, and remove ``mptt`` if not required by other
+  applications.
 * If using Django 1.7 remove ``cms`` and ``menus`` from ``MIGRATION_MODULES`` to support
-  the new migration layout;
-* If migrating for Django 1.6 and below to Django 1.7, remove ``south`` from ``installed_apps``;
+  the new migration layout.
+* If migrating from Django 1.6 and below to Django 1.7, remove ``south`` from ``installed_apps``.
 
 Update the database
 ===================
 
-The migration for mptt to treebeard is handled by the migrations, so just running them will
-update your database:
+The migration from MPTT to ``django-treebeard`` is handled by the migrations, so just running them
+will update your database:
 
 * Rename the plugin table names, either by applying relevant migrations or renaming the table
   manually;