Merge e100636f06 into 8d485da483

docs/api-guide/permissions.md

@@ -110,6 +110,41 @@ To implement a custom permission, override `BasePermission` and implement the `.
 
 The method should return `True` if the request should be granted access, and `False` otherwise.
 
+Example of a custom permission checking authenticated user's first name for an attribute:
+
+```
+    class IsNamedAfterBeatle(permissions.BasePermission):
+        """
+        Custom permission allowing users with first name matching a Beatle
+        """
+        def has_permission(self, request, view, obj=None):
+            if (request.user and
+                request.user.first_name in ("John", "Paul", "Ringo", "George",)):
+                return True
+            else:
+                return False
+```
+
+Example of a custom permission demonstrating object level permissions:
+
+```
+    class IsOwnerOrReadOnly(permissions.BasePermission):
+        """
+        Custom permission to only allow owners of an object to edit, otherwise
+        allow read only access
+        """
+
+        def has_permission(self, request, view, obj=None):
+            if obj is None:
+                if (request.method in SAFE_METHODS or
+                    request.user and
+                    request.user.is_authenticated()):
+                    return True
+
+            # Write permissions are only allowed to the owner
+            return obj.owner == request.user
+```
+
 
 [cite]: https://developer.apple.com/library/mac/#documentation/security/Conceptual/AuthenticationAndAuthorizationGuide/Authorization/Authorization.html
 [authentication]: authentication.md

docs/topics/contributing.md

@@ -4,8 +4,26 @@
 >
 > — [Tim Berners-Lee][cite]
 
+## Get the source
+
+Use `git` to clone the master REST Framework source files to your local systme. If you plan to contribute, 
+to the project, you also need to fork the repo on github. See https://help.github.com/articles/fork-a-repo 
+for more information.
+
 ## Running the tests
 
+Ensure your PYTHONPATH is configured so that the copy of REST Framework from your local git repo is picked up, 
+not any other version you may have installed on your system.
+
+Then, invoked the `runtests/runtests.py` script to execute all unittests.
+
+Here is an example session:
+
+```
+/home/mydir/django-rest-framework$ export PYTHONPATH=/home/mydir/djangorestramework:$PYTHONPATH
+/home/mydir/django-rest-framework$ rest_framework/runtests/runtests.py
+```
+
 ## Building the docs
 
 ## Managing compatibility issues