Merge remote-tracking branch 'upstream/master' into fix-1719

Conflicts:
	rest_framework/templates/rest_framework/base.html

5 files changed, 233 insertions, 7 deletions

diff --git a/docs/topics/2.4-accouncement.md b/docs/topics/2.4-accouncement.md
new file mode 100644
index 00000000..d8e264ff
--- /dev/null
+++ b/docs/topics/2.4-accouncement.md
@@ -0,0 +1,160 @@
+# REST framework 2.4 announcement
+
+The 2.4 release is largely an intermediate step, tying up some outstanding issues prior to the 3.x series.
+
+## Version requirements
+
+Support for Django 1.3 has been dropped.
+The lowest supported version of Django is now 1.4.2.
+
+The current plan is for REST framework to remain in lockstep with [Django's long-term support policy][lts-releases].
+
+## Django 1.7 support
+
+The optional authtoken application now includes support for *both* Django 1.7 schema migrations, *and* for old-style `south` migrations.
+
+**If you are using authtoken, and you want to continue using `south`, you must upgrade your `south` package to version 1.0.**
+
+## Updated test runner
+
+We now have a new test runner for developing against the project,, that uses the excellent [py.test](http://pytest.org) library.
+
+To use it make sure you have first installed the test requirements.
+
+    pip install -r requirements-test.txt
+
+Then run the `runtests.py` script.
+
+    ./runtests.py
+
+The new test runner also includes [flake8](https://flake8.readthedocs.org) code linting, which should help keep our coding style consistent.
+
+#### Test runner flags
+
+Run using a more concise output style.
+
+    ./runtests -q
+
+Run the tests using a more concise output style, no coverage, no flake8.
+
+    ./runtests --fast
+
+Don't run the flake8 code linting.
+
+    ./runtests --nolint
+
+Only run the flake8 code linting, don't run the tests.
+
+    ./runtests --lintonly
+
+Run the tests for a given test case.
+
+    ./runtests MyTestCase
+
+Run the tests for a given test method.
+
+    ./runtests MyTestCase.test_this_method
+
+Shorter form to run the tests for a given test method.
+
+    ./runtests test_this_method
+
+Note: The test case and test method matching is fuzzy and will sometimes run other tests that contain a partial string match to the given  command line input.
+
+## Improved viewset routing
+
+The `@action` and `@link` decorators were inflexible in that they only allowed additional routes to be added against instance style URLs, not against list style URLs.
+
+The `@action` and `@link` decorators have now been moved to pending deprecation, and the `@list_route` and `@detail_route` decorators have been introduced.
+
+Here's an example of using the new decorators. Firstly we have a detail-type route named "set_password" that acts on a single instance, and takes a `pk` argument in the URL. Secondly we have a list-type route named "recent_users" that acts on a queryset, and does not take any arguments in the URL.
+
+    class UserViewSet(viewsets.ModelViewSet):
+        """
+        A viewset that provides the standard actions
+        """
+        queryset = User.objects.all()
+        serializer_class = UserSerializer
+
+        @detail_route(methods=['post'])
+        def set_password(self, request, pk=None):
+            user = self.get_object()
+            serializer = PasswordSerializer(data=request.DATA)
+            if serializer.is_valid():
+                user.set_password(serializer.data['password'])
+                user.save()
+                return Response({'status': 'password set'})
+            else:
+                return Response(serializer.errors,
+                                status=status.HTTP_400_BAD_REQUEST)
+
+        @list_route()
+        def recent_users(self, request):
+            recent_users = User.objects.all().order('-last_login')
+            page = self.paginate_queryset(recent_users)
+            serializer = self.get_pagination_serializer(page)
+            return Response(serializer.data)
+
+For more details, see the [viewsets documentation](../api-guide/viewsets.md).
+
+## Throttle behavior
+
+There's one bugfix in 2.4 that's worth calling out, as it will *invalidate existing throttle caches* when you upgrade.
+
+We've now fixed a typo on the `cache_format` attribute. Previously this was named `"throtte_%(scope)s_%(ident)s"`, it is now `"throttle_%(scope)s_%(ident)s"`.
+
+If you're concerned about the invalidation you have two options.
+
+* Manually pre-populate your cache with the fixed version.
+* Set the `cache_format` attribute on your throttle class in order to retain the previous incorrect spelling.
+
+## Other features
+
+There are also a number of other features and bugfixes as [listed in the release notes][2-4-release-notes]. In particular these include:
+
+[Customizable view name and description functions][view-name-and-description-settings] for use with the browsable API, by using the `VIEW_NAME_FUNCTION` and `VIEW_DESCRIPTION_FUNCTION` settings.
+
+Smarter [client IP identification for throttling][client-ip-identification], with the addition of the `NUM_PROXIES` setting.
+
+Added the standardized `Retry-After` header to throttled responses, as per [RFC 6585](http://tools.ietf.org/html/rfc6585). This should now be used in preference to the custom `X-Trottle-Wait-Seconds` header which will be fully deprecated in 3.0.
+
+## Deprecations
+
+All API changes in 2.3 that previously raised `PendingDeprecationWarning` will now raise a `DeprecationWarning`, which is loud by default.
+
+All API changes in 2.3 that previously raised `DeprecationWarning` have now been removed entirely.
+
+Furter details on these deprecations is available in the [2.3 announcement][2-3-announcement].
+
+## Labels and milestones
+
+Although not strictly part of the 2.4 release it's also worth noting here that we've been working hard towards improving our triage process.
+
+The [labels that we use in GitHub][github-labels] have been cleaned up, and all existing tickets triaged. Any given ticket should have one and only one label, indicating its current state.
+
+We've also [started using milestones][github-milestones] in order to track tickets against particular releases.
+
+---
+
+![Labels and milestones](../img/labels-and-milestones.png)
+
+**Above**: *Overview of our current use of labels and milestones in GitHub.*
+
+---
+
+We hope both of these changes will help make the management process more clear and obvious and help keep tickets well-organised and relevant.
+
+## Next steps
+
+The next planned release will be 3.0, featuring an improved and simplified serializer implementation.
+
+Once again, many thanks to all the generous [backers and sponsors][kickstarter-sponsors] who've helped make this possible!
+
+[lts-releases]: https://docs.djangoproject.com/en/dev/internals/release-process/#long-term-support-lts-releases
+[2-4-release-notes]: ./topics/release-notes/#240
+[view-name-and-description-settings]: ../api-guide/settings/#view-names-and-descriptions
+[client-ip-identification]: ../api-guide/throttling/#how-clients-are-identified
+[2-3-announcement]: ./topics/2.3-announcement
+[github-labels]: https://github.com/tomchristie/django-rest-framework/issues
+[github-milestones]: https://github.com/tomchristie/django-rest-framework/milestones
+[kickstarter-sponsors]: ./topics/kickstarter-announcement/#sponsors
diff --git a/docs/topics/browsable-api.md b/docs/topics/browsable-api.md
index 96cdabe6..ad812f4b 100644
--- a/docs/topics/browsable-api.md
+++ b/docs/topics/browsable-api.md
@@ -69,6 +69,7 @@ For more specific CSS tweaks than simply overriding the default bootstrap theme
 
 All of the blocks available in the browsable API base template that can be used in your `api.html`.
 
+* `body`                       - The entire html `<body>`.
 * `bodyclass`                  - Class attribute for the `<body>` tag, empty by default.
 * `bootstrap_theme`            - CSS for the Bootstrap theme.
 * `bootstrap_navbar_variant`   - CSS class for the navbar.
diff --git a/docs/topics/contributing.md b/docs/topics/contributing.md
index 18a05050..3400bc8f 100644
--- a/docs/topics/contributing.md
+++ b/docs/topics/contributing.md
@@ -62,10 +62,44 @@ To run the tests, clone the repository, and then:
     virtualenv env
     source env/bin/activate
     pip install -r requirements.txt
-    pip install -r optionals.txt
+    pip install -r requirements-test.txt
 
     # Run the tests
-    rest_framework/runtests/runtests.py
+    ./runtests.py
+
+### Test options
+
+Run using a more concise output style.
+
+    ./runtests -q
+
+Run the tests using a more concise output style, no coverage, no flake8.
+
+    ./runtests --fast
+
+Don't run the flake8 code linting.
+
+    ./runtests --nolint
+
+Only run the flake8 code linting, don't run the tests.
+
+    ./runtests --lintonly
+
+Run the tests for a given test case.
+
+    ./runtests MyTestCase
+
+Run the tests for a given test method.
+
+    ./runtests MyTestCase.test_this_method
+
+Shorter form to run the tests for a given test method.
+
+    ./runtests test_this_method
+
+Note: The test case and test method matching is fuzzy and will sometimes run other tests that contain a partial string match to the given  command line input.
+
+### Running against multiple environments
 
 You can also use the excellent [tox][tox] testing tool to run the tests against all supported versions of Python and Django.  Install `tox` globally, and then simply run:
 
diff --git a/docs/topics/kickstarter-announcement.md b/docs/topics/kickstarter-announcement.md
index 84dc8511..6d091064 100644
--- a/docs/topics/kickstarter-announcement.md
+++ b/docs/topics/kickstarter-announcement.md
@@ -81,6 +81,8 @@ Our gold sponsors include companies large and small. Many thanks for their signi
 <li><a href="http://lightningkite.com/" rel="nofollow" style="background-image:url(../img/sponsors/2-lightning_kite.png);">Lightning Kite</a></li>
 <li><a href="https://opbeat.com/" rel="nofollow" style="background-image:url(../img/sponsors/2-opbeat.png);">Opbeat</a></li>
 <li><a href="https://koordinates.com" rel="nofollow" style="background-image:url(../img/sponsors/2-koordinates.png);">Koordinates</a></li>
+<li><a href="http://pulsecode.ca" rel="nofollow" style="background-image:url(../img/sponsors/2-pulsecode.png);">Pulsecode Inc.</a></li>
+<li><a href="http://singinghorsestudio.com" rel="nofollow" style="background-image:url(../img/sponsors/2-singing-horse.png);">Singing Horse Studio. Ltd.</a></li>
 <li><a href="https://www.heroku.com/" rel="nofollow" style="background-image:url(../img/sponsors/2-heroku.png);">Heroku</a></li>
 <li><a href="https://www.galileo-press.de/" rel="nofollow" style="background-image:url(../img/sponsors/2-galileo_press.png);">Galileo Press</a></li>
 <li><a href="http://www.securitycompass.com/" rel="nofollow" style="background-image:url(../img/sponsors/2-security_compass.png);">Security Compass</a></li>
@@ -95,7 +97,7 @@ Our gold sponsors include companies large and small. Many thanks for their signi
 
 <div style="clear: both; padding-bottom: 40px;"></div>
 
-**Individual backers**: Xitij Ritesh Patel, Howard Sandford, Simon Haugk.
+**Individual backers**: Simon Haugk.
 
 ---
 
diff --git a/docs/topics/release-notes.md b/docs/topics/release-notes.md
index ea4c912c..a2b4782f 100644
--- a/docs/topics/release-notes.md
+++ b/docs/topics/release-notes.md
@@ -38,6 +38,35 @@ You can determine your currently installed version using `pip freeze`:
 
 ---
 
+## 2.4.x series
+
+### 2.4.0
+
+**Django version requirements**: The lowest supported version of Django is now 1.4.2.
+
+**South version requirements**: This note applies to any users using the optional `authtoken` application, which includes an associated database migration. You must now *either* upgrade your `south` package to version 1.0, *or* instead use the built-in migration support available with Django 1.7.
+
+* Added compatibility with Django 1.7's database migration support.
+* New test runner, using `py.test`.
+* `@detail_route` and `@list_route` decorators replace `@action` and `@link`.
+* Support customizable view name and description functions, using the `VIEW_NAME_FUNCTION` and `VIEW_DESCRIPTION_FUNCTION` settings.
+* Added `NUM_PROXIES` setting for smarter client IP identification.
+* Added `MAX_PAGINATE_BY` setting and `max_paginate_by` generic view attribute.
+* Added `Retry-After` header to throttled responses, as per [RFC 6585](http://tools.ietf.org/html/rfc6585). This should now be used in preference to the custom `X-Trottle-Wait-Seconds` header which will be fully deprecated in 3.0.
+* Added `cache` attribute to throttles to allow overriding of default cache.
+* Added `lookup_value_regex` attribute to routers, to allow the URL argument matching to be constrainted by the user.
+* Added `allow_none` option to `CharField`.
+* Support Django's standard `status_code` class attribute on responses.
+* More intuitive behavior on the test client, as `client.logout()` now also removes any credentials that have been set.
+* Bugfix: `?page_size=0` query parameter now falls back to default page size for view, instead of always turning pagination off.
+* Bugfix: Always uppercase `X-Http-Method-Override` methods.
+* Bugfix: Copy `filter_backends` list before returning it, in order to prevent view code from mutating the class attribute itself.
+* Bugfix: Set the `.action` attribute on viewsets when introspected by `OPTIONS` for testing permissions on the view.
+* Bugfix: Ensure `ValueError` raised during deserialization results in a error list rather than a single error. This is now consistent with other validation errors.
+* Bugfix: Fix `cache_format` typo on throttle classes, was `"throtte_%(scope)s_%(ident)s"`. Note that this will invalidate existing throttle caches.
+
+---
+
 ## 2.3.x series
 
 ### 2.3.14
@@ -169,9 +198,9 @@ You can determine your currently installed version using `pip freeze`:
 * Added `trailing_slash` option to routers.
 * Include support for `HttpStreamingResponse`.
 * Support wider range of default serializer validation when used with custom model fields.
-* UTF-8 Support for browsable API descriptions.  
+* UTF-8 Support for browsable API descriptions.
 * OAuth2 provider uses timezone aware datetimes when supported.
-* Bugfix: Return error correctly when OAuth non-existent consumer occurs. 
+* Bugfix: Return error correctly when OAuth non-existent consumer occurs.
 * Bugfix: Allow `FileUploadParser` to correctly filename if provided as URL kwarg.
 * Bugfix: Fix `ScopedRateThrottle`.
 
@@ -212,7 +241,7 @@ You can determine your currently installed version using `pip freeze`:
 * Added SearchFilter
 * Added OrderingFilter
 * Added GenericViewSet
-* Bugfix: Multiple `@action` and `@link` methods now allowed on viewsets. 
+* Bugfix: Multiple `@action` and `@link` methods now allowed on viewsets.
 * Bugfix: Fix API Root view issue with DjangoModelPermissions
 
 ### 2.3.2
@@ -265,7 +294,7 @@ You can determine your currently installed version using `pip freeze`:
 * Long HTTP headers in browsable API are broken in multiple lines when possible.
 * Bugfix: Fix regression with DjangoFilterBackend not worthing correctly with single object views.
 * Bugfix: OAuth should fail hard when invalid token used.
-* Bugfix: Fix serializer potentially returning `None` object for models that define `__bool__` or `__len__`. 
+* Bugfix: Fix serializer potentially returning `None` object for models that define `__bool__` or `__len__`.
 
 ### 2.2.5