3.4.0 Release (#4258)

* 3.4.0 Release

* Version 3.4 release

* Full release notes

* Update translation files

* Update release documentation

* Update release notes

* Docs on supporting alternate schema formats

* Add schema_renderers to DefaultRouter

Author: lovelydinosaur

docs/api-guide/schemas.md

@@ -68,7 +68,7 @@ has to be rendered into the actual bytes that are used in the response.
 REST framework includes a renderer class for handling this media type, which
 is available as `renderers.CoreJSONRenderer`.
 
-Other schema formats such as [Open API][open-api] (Formerly "Swagger"),
+Other schema formats such as [Open API][open-api] ("Swagger"),
 [JSON HyperSchema][json-hyperschema], or [API Blueprint][api-blueprint] can
 also be supported by implementing a custom renderer class.
 
@@ -126,16 +126,29 @@ that include the Core JSON media type in their `Accept` header.
     }
 
 This is a great zero-configuration option for when you want to get up and
-running really quickly. If you want a little more flexibility over the
-schema output then you'll need to consider using `SchemaGenerator` instead.
+running really quickly.
+
+The only other available option to `DefaultRouter` is `schema_renderers`, which
+may be used to pass the set of renderer classes that can be used to render
+schema output.
+
+    from rest_framework.renderers import CoreJSONRenderer
+    from my_custom_package import APIBlueprintRenderer
+
+    router = DefaultRouter(schema_title='Server Monitoring API', schema_renderers=[
+        CoreJSONRenderer, APIBlueprintRenderer
+    ])
+
+If you want more flexibility over the schema output then you'll need to consider
+using `SchemaGenerator` instead.
 
 ## Using SchemaGenerator
 
 The most common way to add a schema to your API is to use the `SchemaGenerator`
 class to auto-generate the `Document` instance, and to return that from a view.
 
 This option gives you the flexibility of setting up the schema endpoint
-with whatever behaviour you want. For example, you can apply different
+with whatever behavior you want. For example, you can apply different
 permission, throttling or authentication policies to the schema endpoint.
 
 Here's an example of using `SchemaGenerator` together with a view to
@@ -210,6 +223,32 @@ You could then either:
 
 ---
 
+# Alternate schema formats
+
+In order to support an alternate schema format, you need to implement a custom renderer
+class that handles converting a `Document` instance into a bytestring representation.
+
+If there is a Core API codec package that supports encoding into the format you
+want to use then implementing the renderer class can be done by using the codec.
+
+## Example
+
+For example, the `openapi_codec` package provides support for encoding or decoding
+to the Open API ("Swagger") format:
+
+    from rest_framework import renderers
+    from openapi_codec import OpenAPICodec
+
+    class SwaggerRenderer(renderers.BaseRenderer):
+        media_type = 'application/openapi+json;version=2.0'
+        format = 'swagger'
+
+        def render(self, data, media_type=None, renderer_context=None):
+            codec = OpenAPICodec()
+            return OpenAPICodec.dump(data)
+
+---
+
 # API Reference
 
 ## SchemaGenerator

docs/index.md

@@ -78,7 +78,7 @@ Right now we're over 58% of the way towards achieving that.
 </ul>
 <div style="clear: both; padding-bottom: 20px;"></div>
 
-*Many thanks to all our [awesome sponsors][sponsors], and in particular to our premium backers, [Rover](http://jobs.rover.com/), [Sentry](https://getsentry.com/welcome/), and [Stream](https://getstream.io/?utm_source=drf&utm_medium=banner&utm_campaign=drf).*
+*Many thanks to all our [wonderful sponsors][sponsors], and in particular to our premium backers, [Rover](http://jobs.rover.com/), [Sentry](https://getsentry.com/welcome/), and [Stream](https://getstream.io/?utm_source=drf&utm_medium=banner&utm_campaign=drf).*
 
 ---
 
@@ -243,6 +243,7 @@ General guides to using REST framework.
 * [3.1 Announcement][3.1-announcement]
 * [3.2 Announcement][3.2-announcement]
 * [3.3 Announcement][3.3-announcement]
+* [3.4 Announcement][3.4-announcement]
 * [Kickstarter Announcement][kickstarter-announcement]
 * [Mozilla Grant][mozilla-grant]
 * [Funding][funding]
@@ -368,6 +369,7 @@ OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 [3.1-announcement]: topics/3.1-announcement.md
 [3.2-announcement]: topics/3.2-announcement.md
 [3.3-announcement]: topics/3.3-announcement.md
+[3.4-announcement]: topics/3.4-announcement.md
 [kickstarter-announcement]: topics/kickstarter-announcement.md
 [mozilla-grant]: topics/mozilla-grant.md
 [funding]: topics/funding.md

docs/topics/3.4-announcement.md

@@ -0,0 +1,172 @@
+<style>
+.promo li a {
+    float: left;
+    width: 130px;
+    height: 20px;
+    text-align: center;
+    margin: 10px 30px;
+    padding: 150px 0 0 0;
+    background-position: 0 50%;
+    background-size: 130px auto;
+    background-repeat: no-repeat;
+    font-size: 120%;
+    color: black;
+}
+.promo li {
+    list-style: none;
+}
+</style>
+
+# Django REST framework 3.4
+
+The 3.4 release is the first in a planned series that will be addressing schema
+generation, hypermedia support, API clients, and finally realtime support.
+
+---
+
+## Funding
+
+The 3.4 release has been made possible a recent [Mozilla grant][moss], and by our
+[collaborative funding model][funding]. If you use REST framework commercially, and would
+like to see this work continue, we strongly encourage you to invest in its
+continued development by **[signing up for a paid plan][funding]**.
+
+The initial aim is to provide a single full-time position on REST framework.
+Right now we're over 60% of the way towards achieving that.
+*Every single sign-up makes a significant impact.*
+
+<ul class="premium-promo promo">
+    <li><a href="http://jobs.rover.com/" style="background-image: url(https://fund-rest-framework.s3.amazonaws.com/rover_130x130.png)">Rover.com</a></li>
+    <li><a href="https://getsentry.com/welcome/" style="background-image: url(https://fund-rest-framework.s3.amazonaws.com/sentry130.png)">Sentry</a></li>
+    <li><a href="https://getstream.io/?utm_source=drf&utm_medium=banner&utm_campaign=drf" style="background-image: url(https://fund-rest-framework.s3.amazonaws.com/stream-130.png)">Stream</a></li>
+</ul>
+<div style="clear: both; padding-bottom: 20px;"></div>
+
+*Many thanks to all our [awesome sponsors][sponsors], and in particular to our premium backers, [Rover](http://jobs.rover.com/), [Sentry](https://getsentry.com/welcome/), and [Stream](https://getstream.io/?utm_source=drf&utm_medium=banner&utm_campaign=drf).*
+
+---
+
+## Schemas & client libraries
+
+REST framework 3.4 brings built-in support for generating API schemas.
+
+We provide this support by using [Core API][core-api], a Document Object Model
+for describing APIs.
+
+Because Core API represents the API schema in an format-independent
+manner, we're able to render the Core API `Document` object into many different
+schema formats, by allowing the renderer class to determine how the internal
+representation maps onto the external schema format.
+
+This approach should also open the door to a range of auto-generated API
+documentation options in the future, by rendering the `Document` object into
+HTML documentation pages.
+
+Alongside the built-in schema support, we're also now providing the following:
+
+* A [command line tool][command-line-client] for interacting with APIs.
+* A [Python client library][client-library] for interacting with APIs.
+
+These API clients are dynamically driven, and able to interact with any API
+that exposes a supported schema format.
+
+Dynamically driven clients allow you to interact with an API at an application
+layer interface, rather than a network layer interface, while still providing
+the benefits of RESTful Web API design.
+
+We're expecting to expand the range of languages that we provide client libraries
+for over the coming months.
+
+---
+
+Current support for schema formats is as follows:
+
+Name                             | Support                             | PyPI package
+---------------------------------|-------------------------------------|--------------------------------
+[Core JSON][core-json]           | Schema generation & client support. | Built-in support in `coreapi`.
+[Swagger / OpenAPI][swagger]     | Schema generation & client support. | The `openapi-codec` package.
+[JSON Hyper-Schema][hyperschema] | Currrently client support only.     | The `hyperschema-codec` package.
+[API Blueprint][api-blueprint]   | Not yet available.                  | Not yet available.
+
+---
+
+You can read more about any of this new functionality in the following:
+
+* New tutorial section on [schemas & client libraries][tut-7].
+* Documentation page on [schema generation][schema-generation].
+* Topic page on [API clients][api-clients].
+
+It is also worth noting that Marc Gibbons is currently working towards a 2.0 release of
+the popular Django REST Swagger package, which will tie in with our new built-in support.
+
+---
+
+## Supported versions
+
+The 3.4.0 release adds support for Django 1.10.
+
+The following versions of Python and Django are now supported:
+
+* Django versions 1.8, 1.9, and 1.10.
+* Python versions 2.7, 3.2(\*), 3.3(\*), 3.4, 3.5.
+
+(\*) Note that Python 3.2 and 3.3 are not supported from Django 1.9 onwards.
+
+---
+
+## Deprecations and changes
+
+The 3.4 release includes very limited deprecation or behavioral changes, and
+should present a straightforward upgrade.
+
+#### Use fields or exclude on serializer classes.
+
+The following change in 3.3.0 is now escalated from "pending deprecation" to
+"deprecated". Its usage will continue to function but will raise warnings:
+
+`ModelSerializer` and `HyperlinkedModelSerializer` should include either a `fields`
+option, or an `exclude` option. The `fields = '__all__'` shortcut may be used
+to explicitly include all fields.
+
+#### Microsecond precision when returning time or datetime
+
+Using the default JSON renderer and directly returning a `datetime` or `time`
+instance will now render with microsecond precision (6 digits), rather than
+millisecond precision (3 digits). This makes the output format consistent with the
+default string output of `serializers.DateTimeField` and `serializers.TimeField`.
+
+This change *does not affect the default behavior when using serializers*,
+which is to serialize `datetime` and `time` instances into strings with
+microsecond precision.
+
+The serializer behavior can be modified if needed, using the `DATETIME_FORMAT`
+and `TIME_FORMAT` settings.
+
+The renderer behavior can be modified by setting a custom `encoder_class`
+attribute on a `JSONRenderer` subclass.
+
+---
+
+## Other improvements
+
+This release includes further work from a huge number of [pull requests and issues][milestone].
+
+Many thanks to all our contributors who've been involved in the release, either through raising issues, giving feedback, improving the documentation, or suggesting and implementing code changes.
+
+The full set of itemized release notes [are available here][release-notes].
+
+[sponsors]: https://fund.django-rest-framework.org/topics/funding/#our-sponsors
+[moss]: mozilla-grant.md
+[funding]: funding.md
+[core-api]: http://www.coreapi.org/
+[command-line-client]: api-clients#command-line-client
+[client-library]: api-clients#python-client-library
+[core-json]: http://www.coreapi.org/specification/encoding/#core-json-encoding
+[swagger]: https://openapis.org/specification
+[hyperschema]: http://json-schema.org/latest/json-schema-hypermedia.html
+[api-blueprint]: https://apiblueprint.org/
+[tut-7]: ../../tutorial/7-schemas-and-client-libraries/
+[schema-generation]: ../../api-guide/schemas/
+[api-clients]: api-clients.md
+[milestone]: https://github.com/tomchristie/django-rest-framework/milestone/35
+[release-notes]: release-notes#34

docs/topics/api-clients.md

@@ -59,7 +59,7 @@ exposes a supported schema format.
 To install the Core API command line client, use `pip`.
 
 Note that the command-line client is a separate package to the
-python client library `coreapi`. Make sure to install `coreapi-cli`.
+python client library. Make sure to install `coreapi-cli`.
 
     $ pip install coreapi-cli