Doc updates for FieldTracker -> ModelTracker transition.

CHANGES.rst

@@ -4,6 +4,9 @@ CHANGES
 tip (unreleased)
 ----------------
 
+- Introduced ``FieldTracker`` as replacement for ``ModelTracker``, which is now
+  deprecated.
+
 - ``PassThroughManager.for_queryset_class()`` no longer ignores superclass
   ``get_query_set``. Thanks Andy Freeland.
 

README.rst

@@ -207,6 +207,7 @@ Assignment to ``a.body`` is equivalent to assignment to
 ``a.body.content``.
 
 .. note::
+
     a.body.excerpt is only updated when a.save() is called
 
 
@@ -436,11 +437,40 @@ last saved.  An example of applying ``FieldTracker`` to a model:
 
         tracker = FieldTracker()
 
+.. note::
+
+    ``django-model-utils`` 1.3.0 introduced the ``ModelTracker`` object for
+    tracking changes to model field values. Unfortunately ``ModelTracker``
+    suffered from some serious flaws in its handling of ``ForeignKey`` fields,
+    potentially resulting in many extra database queries if a ``ForeignKey``
+    field was tracked. In order to avoid breaking API backwards-compatibility,
+    ``ModelTracker`` retains the previous behavior but is deprecated, and
+    ``FieldTracker`` has been introduced to provide better ``ForeignKey``
+    handling. All uses of ``ModelTracker`` should be replaced by
+    ``FieldTracker``.
+
+    Summary of differences between ``ModelTracker`` and ``FieldTracker``:
+
+    * The previous value returned for a tracked ``ForeignKey`` field will now
+      be the raw ID rather than the full object (avoiding extra database
+      queries). (GH-43)
+
+    * The ``changed()`` method no longer returns the empty dictionary for all
+      unsaved instances; rather, ``None`` is considered to be the initial value
+      of all fields if the model has never been saved, thus ``changed()`` on an
+      unsaved instance will return a dictionary containing all fields whose
+      current value is not ``None``.
+
+    * The ``has_changed()`` method no longer crashes after an object's first
+      save. (GH-53).
+
+
 Accessing a field tracker
 -------------------------
 
 There are multiple methods available for checking for changes in model fields.
 
+
 previous
 ~~~~~~~~
 Returns the value of the given field during the last save:
@@ -454,6 +484,7 @@ Returns the value of the given field during the last save:
 
 Returns ``None`` when the model instance isn't saved yet.
 
+
 has_changed
 ~~~~~~~~~~~
 Returns ``True`` if the given field has changed since the last save:
@@ -470,6 +501,7 @@ Returns ``True`` if the given field has changed since the last save:
 The ``has_changed`` method relies on ``previous`` to determine whether a
 field's values has changed.
 
+
 changed
 ~~~~~~~
 Returns a dictionary of all fields that have been changed since the last save