Notes on object-level permissions.

docs/topics/2.2-announcement.md

@@ -101,6 +101,45 @@ In keeping with Django's CharField API, REST framework's `CharField` will only e
 
 The `blank` keyword argument will continue to function, but will raise a `PendingDeprecationWarning`.
 
+### Simpler object-level permissions
+
+Custom permissions classes previously used the signatute `.has_permission(self, request, view, obj=None)`.  This method would be called twice, firstly for the global permissions check, with the `obj` parameter set to `None`, and again for the object-level permissions check when appropriate, with the `obj` parameter set to the relevant model instance.
+
+The global permissions check and object-level permissions check are now seperated into two seperate methods, which gives a cleaner, more obvious API.
+
+* Global permission checks now use the `.has_permission(self, request, view)` signature.
+* Object-level permission checks use a new method `.has_object_permission(self, request, view, obj)`.
+
+For example, the following custom permission class:
+
+    class IsOwner(permissions.BasePermission):
+        """
+        Custom permission to only allow owners of an object to view or edit it.
+        Model instances are expected to include an `owner` attribute.
+        """
+
+        def has_permission(self, request, view, obj=None):
+            if obj is None:
+                # Ignore global permissions check
+                return True
+
+            return obj.owner == request.user
+
+Now becomes:
+
+    class IsOwner(permissions.BasePermission):
+        """
+        Custom permission to only allow owners of an object to view or edit it.
+        Model instances are expected to include an `owner` attribute.
+        """
+
+        def has_object_permission(self, request, view, obj):
+            return obj.owner == request.user
+
+If you're overriding the `BasePermission` class, the old-style signature will continue to function, and will correctly handle both global and object-level permissions checks, but it's use will raise a `PendingDeprecationWarning`.
+
+Note also that the usage of the internal APIs for permission checking on the `View` class has been cleaned up slightly, and is now documented and subject to the deprecation policy in all future versions.
+
 [xordoquy]: https://github.com/xordoquy
 [django-python-3]: https://docs.djangoproject.com/en/dev/faq/install/#can-i-use-django-with-python-3
 [porting-python-3]: https://docs.djangoproject.com/en/dev/topics/python3/