Documentation for new migrations

digi604 · Oct 12, 2012 · e35d6f8 · e35d6f8
1 parent 7091131
commit e35d6f8
Show file tree

Hide file tree

Showing 2 changed files with 30 additions and 3 deletions.
diff --git a/docs/index.rst b/docs/index.rst
@@ -13,6 +13,13 @@ This document refers to version |release|
 Install
 *******
 
+.. warning::
+    In version 2.4 migrations have been completely rewritten to fix issues
+    with newer south releases.
+    If upgrading from prior 2.3.2 releases, please refer to
+    :ref:`migrations-upgrade`
+
+
 .. toctree::
     :maxdepth: 1
 
@@ -24,6 +31,7 @@ Install
     upgrade/2.2
     upgrade/2.1
 
+
 ***************
 Getting Started
 ***************

diff --git a/docs/upgrade/2.4.rst b/docs/upgrade/2.4.rst
@@ -123,14 +123,34 @@ The following settings are not needed any more and have been removed:
 Please remove them from your settings.py
 
 
+.. _migrations-upgrade:
+
+Migrations overhaul
+===================
+In version 2.4 migrations have been completely rewritten to fix issues with
+newer South releases.
+
+To ease upgrading process migration numbering and naming have not been changed,
+but only the first one for each application has actual migration code, so it's of
+utmost importance that you have an up to date migration history.
+
+To ensure this, when upgrading from 2.3.1 and older releases, please upgrate to
+2.3.3 first, execute all the migrations and then move to 2.4.
+
+For the two step upgrade process do the following in your project main directory ::
+
+    pip install django-cms==2.3.3
+    python manage.py syncdb
+    python manage.py migrate
+    pip install django-cms==2.4
+
+
 CMS_FLAT_URLS
 =============
 
 Was marked deprecated in 2.3 and has now been removed.
 
 
-
-
 ..
     Feature description
 
@@ -151,7 +171,6 @@ If you are running django 1.3.X you need to install django-i18nurls, if you want
 multilingual features. The cms.urls needs to be in a i18n url pattern.
 
 
-
 ********************
 Pending deprecations
 ********************