Begin v3.10 Release Announcement.

carltongibson · carltongibson · commit 3fb872b25211 · 2019-06-09T14:52:07.000+02:00
diff --git a/docs/community/3.10-announcement.md b/docs/community/3.10-announcement.md
@@ -0,0 +1,104 @@
+
+# Django REST framework 3.10
+
+
+* Reworked OpenAPI schema generation.
+* Python 3 only.
+
+
+## OpenAPI Schema Generation.
+
+Since we first introduced schema support in Django REST Framework 3.5, OpenAPI has emerged as the widely adopted standard for modelling Web APIs.
+
+This release deprecates the old CoreAPI based schema generation, and introduces improved OpenAPI schema generation in its place.
+
+----
+
+**Switching mode between `CoreAPI` and `OpenAPI`**
+
+Both the `generateschema` management command and `get_schema_view()` helper
+function will automatically switch between `CoreAPI` and `OpenAPI` modes,
+depending on the value of `api_settings.DEFAULT_SCHEMA_CLASS`.
+
+If `api_settings.DEFAULT_SCHEMA_CLASS` is a subclass of
+`rest_framework.schemas.coreapi.AutoSchema` then `CoreAPI` mode will be
+selected. Otherwise the new `OpenAPI` will apply.
+
+This means that, unless you previously overrode
+`api_settings.DEFAULT_SCHEMA_CLASS`, you automatically be opted-in to the new
+`OpenAPI` based schemas.
+
+You can continue to use CoreAPI schemas by setting the appropriate default
+schema class:
+
+```python
+# In settings.py
+REST_FRAMEWORK = {
+    'DEFAULT_SCHEMA_CLASS': 'rest_framework.schemas.coreapi.AutoSchema',
+}
+```
+
+----
+
+### Quickstart
+
+To get going with `OpenAPI` schemas, use the `get_schema_view()` shortcut.
+
+In your `urls.py`:
+
+```python
+from rest_framework.schemas import get_schema_view()
+
+urlpatterns = [
+    # ...
+    # Use the `get_schema_view()` helper to add a `SchemaView` to project URLs.
+    #   * `title` and `description` parameters are passed to `SchemaGenerator`.
+    #   * Provide view name for use with `reverse()`.
+    path('openapi', get_schema_view(
+        title="Your Project",
+        description="API for all things …"
+    ), name='openapi-schema'),
+    # ...
+]
+```
+
+See the Schemas documentation for more details.
+
+### Feature Roadmap
+
+For v3.7 (with `CoreAPI`) we tried to anticipate customizations that people
+were likely to need. (Introducing `manual_fields` and `ManaualSchema`, for
+example.) These were under-utilised. They weren't the right abstractions.
+
+So, for a fresh start with `OpenAPI`, customizing schema generation has two
+simple rules:
+
+* Subclass `SchemaGenerator` for schema-level cusomizations.
+* Subclass `AutoSchema` for view-level customizations.
+
+We'll wait to see what subclasses people actually come up with, for the
+customizations they actually need, before trying to bring that back into the
+core framework.
+
+There are two kinds of changes that easily predictable:
+
+* General improvements which fill in gaps in the automatic schema generation.
+* More use-case specific adjustments, which adjust the API of `SchemaGenerator`
+  or `AutoSchema`
+
+We'll aim to bring the first type of change quickly in point releases. For the
+second kind we'd like to adopt a slower approach, to make sure we keep the API
+simple, and as widely applicable as possible, before we bring in API changes.
+
+We trust that approach makes sense.
+
+### Deprecating CoreAPI Schema Generation.
+
+The in-built docs that were introduced in Django REST Framework v3.5 were built on CoreAPI. These are now deprecated. You may continue to use them but they will be **removed in Django REST Framework v 3.12**.
+
+You should migrate to using the new OpenAPI based schema generation as soon as you can.
+
+We have removed the old documentation for the CoreAPI based schema generation.
+You may view the [Legacy CoreAPI documentation here][legacy-core-api-docs].
+
+[legacy-core-api-docs]:https://github.com/encode/django-rest-framework/blob/master/docs/coreapi/index.md
diff --git a/mkdocs.yml b/mkdocs.yml
@@ -64,6 +64,7 @@ pages:
      - 'Contributing to REST framework': 'community/contributing.md'
      - 'Project management': 'community/project-management.md'
      - 'Release Notes': 'community/release-notes.md'
+     - '3.10 Announcement': 'community/3.10-announcement.md'
      - '3.9 Announcement': 'community/3.9-announcement.md'
      - '3.8 Announcement': 'community/3.8-announcement.md'
      - '3.7 Announcement': 'community/3.7-announcement.md'
