Add upgrade instructions for 2.5.0

README.rst

@@ -4,6 +4,8 @@ factory_boy
 .. image:: https://secure.travis-ci.org/rbarrois/factory_boy.png?branch=master
     :target: http://travis-ci.org/rbarrois/factory_boy/
 
+Latest release: `2.5.0 <http://factoryboy.readthedocs.org/en/latest/changelog.html#v2-5-0>`_ (includes breaking changes, see the `ChangeLog <http://factoryboy.readthedocs.org/en/latest/changelog.html>`_)
+
 factory_boy is a fixtures replacement based on thoughtbot's `factory_girl <http://github.com/thoughtbot/factory_girl>`_.
 
 As a fixtures replacement tool, it aims to replace static, hard to maintain fixtures
@@ -281,12 +283,12 @@ This will yield messages similar to those (artificial indentation):
 ORM Support
 """""""""""
 
-factory_boy has specific support for a few ORMs, through specific :class:`~factory.Factory` subclasses:
+factory_boy has specific support for a few ORMs, through specific ``factory.Factory`` subclasses:
 
-* Django, with :class:`~factory.django.DjangoModelFactory`
-* Mogo, with :class:`~factory.mogo.MogoFactory`
-* MongoEngine, with :class:`~factory.mongoengine.MongoEngineFactory`
-* SQLAlchemy, with :class:`~factory.alchemy.SQLAlchemyModelFactory`
+* Django, with ``factory.django.DjangoModelFactory``
+* Mogo, with ``factory.mogo.MogoFactory``
+* MongoEngine, with ``factory.mongoengine.MongoEngineFactory``
+* SQLAlchemy, with ``factory.alchemy.SQLAlchemyModelFactory``
 
 Contributing
 ------------

docs/changelog.rst

@@ -35,6 +35,36 @@ ChangeLog
 .. warning:: Version 2.5.0 removes the 'auto-magical sequence setup' bug-and-feature.
              This could trigger some bugs when tests expected a non-zero sequence reference.
 
+Upgrading
+"""""""""
+
+.. warning:: Version 2.5.0 removes features that were marked as deprecated in :ref:`v2.4.0 <v2.4.0>`.
+
+All ``FACTORY_*``-style attributes are now declared in a ``class Meta:`` section:
+
+.. code-block:: python
+
+    # Old-style, deprecated
+    class MyFactory(factory.Factory):
+        FACTORY_FOR = models.MyModel
+        FACTORY_HIDDEN_ARGS = ['a', 'b', 'c']
+
+    # New-style
+    class MyFactory(factory.Factory):
+        class Meta:
+            model = models.MyModel
+            exclude = ['a', 'b', 'c']
+
+A simple shell command to upgrade the code would be:
+
+.. code-block:: sh
+
+    # sed -i: inplace update
+    # grep -l: only file names, not matching lines
+    sed -i 's/FACTORY_FOR =/class Meta:\n        model =/' $(grep -l FACTORY_FOR $(find . -name '*.py'))
+
+This takes care of all ``FACTORY_FOR`` occurences; the files containing other attributes to rename can be found with ``grep -R  FACTORY .``
+
 
 .. _v2.4.1: