Update release notes and documentation for 2.2.0

README.md

@@ -39,14 +39,46 @@ There is also a sandbox API you can use for testing purposes, [available here][s
 
 # Installation
 
-Install using `pip`...
+Install using `pip`, including any optional packages you want...
 
     pip install djangorestframework
+    pip install markdown  # Markdown support for the browseable API.
+    pip install pyyaml    # YAML content-type support.
+    pip install django-filter  # Filtering support
 
 ...or clone the project from github.
 
     git clone git@github.com:tomchristie/django-rest-framework.git
+    cd django-rest-framework
     pip install -r requirements.txt
+    pip install -r optionals.txt
+
+Add `'rest_framework'` to your `INSTALLED_APPS` setting.
+
+    INSTALLED_APPS = (
+        ...
+        'rest_framework',        
+    )
+
+## Browseable API requirements
+
+If you're intending to use the browseable API you'll also want to also ensure you include `'django.contrib.staticfiles'` in your `INSTALLED_APPS` setting.
+
+    INSTALLED_APPS = (
+        ...
+        'django.contrib.staticfiles',
+        'rest_framework',
+    )
+
+You'll proabably also want to add REST framework's login and logout views.
+Add the following to your root `urls.py` file.
+
+    urlpatterns = patterns('',
+        ...
+        url(r'^api-auth/', include('rest_framework.urls', namespace='rest_framework'))
+    )
+
+Note that the URL path can be whatever you want, but you must include `'rest_framework.urls'` with the `'rest_framework'` namespace.
 
 # Development
 

docs/index.md

@@ -15,7 +15,7 @@ Django REST framework is a lightweight library that makes it easy to build Web A
 
 Web APIs built using REST framework are fully self-describing and web browseable - a huge useability win for your developers.  It also supports a wide range of media types, authentication and permission policies out of the box.
 
-If you are considering using REST framework for your API, we recommend reading the [REST framework 2 announcment][rest-framework-2-announcement] which gives a good overview of the framework and it's capabilities.
+If you are considering using REST framework for your API, we recommend reading the [REST framework 2 announcement][rest-framework-2-announcement] which gives a good overview of the framework and it's capabilities.
 
 There is also a sandbox API you can use for testing purposes, [available here][sandbox].
 
@@ -52,21 +52,32 @@ Install using `pip`, including any optional packages you want...
     pip install -r requirements.txt
     pip install -r optionals.txt
 
-Add `rest_framework` to your `INSTALLED_APPS`.
+Add `'rest_framework'` to your `INSTALLED_APPS` setting.
 
     INSTALLED_APPS = (
         ...
         'rest_framework',        
     )
 
-If you're intending to use the browseable API you'll want to add REST framework's login and logout views.  Add the following to your root `urls.py` file.
+### Browseable API requirements
+
+If you're intending to use the browseable API you'll also want to also ensure you include `'django.contrib.staticfiles'` in your `INSTALLED_APPS` setting.
+
+    INSTALLED_APPS = (
+        ...
+        'django.contrib.staticfiles',
+        'rest_framework',
+    )
+
+You'll proabably also want to add REST framework's login and logout views.
+Add the following to your root `urls.py` file.
 
     urlpatterns = patterns('',
         ...
         url(r'^api-auth/', include('rest_framework.urls', namespace='rest_framework'))
     )
 
-Note that the URL path can be whatever you want, but you must include `rest_framework.urls` with the `rest_framework` namespace.
+Note that the URL path can be whatever you want, but you must include `'rest_framework.urls'` with the `'rest_framework'` namespace.
 
 ## Quickstart
 

docs/topics/release-notes.md

@@ -4,12 +4,27 @@
 >
 > — Eric S. Raymond, [The Cathedral and the Bazaar][cite].
 
-## 2.1.x series
+## Versioning
+
+Minor version numbers (0.0.x) are used for changes that are API compatible.  You should be able to upgrade between minor point releases without any other code changes.
+
+Medium version numbers (0.x.0) may include minor API changes.  You should read the release notes carefully before upgrading between medium point releases.
 
-### Master
+## 2.2.x series
 
+### 2.2.0
+
+**Date**: 27th Dec 2012
+
+* Support configurable `STATICFILES_STORAGE` storage.
 * Bugfix: Related fields now respect the required flag, and may be required=False.
 
+**API-incompatible changes**: From 2.2.0 Onwards you must make sure to include `'django.contrib.staticfiles'` in your `INSTALLED_APPS`.  This is in line with Django's 1.4's recommended usage of [the `'staticfiles'` template tag][staticfiles14] instead of Django 1.3's recommended usage of [the `'static'` template tag][staticfiles13].
+
+---
+
+## 2.1.x series
+
 ### 2.1.12
 
 **Date**: 21st Dec 2012
@@ -105,7 +120,7 @@
 
 * Support use of HTML exception templates.  Eg. `403.html`
 * Hyperlinked fields take optional `slug_field`, `slug_url_kwarg` and `pk_url_kwarg` arguments.
-* Bugfix: Deal with optional trailing slashs properly when generating breadcrumbs.
+* Bugfix: Deal with optional trailing slashes properly when generating breadcrumbs.
 * Bugfix: Make textareas same width as other fields in browsable API.
 * Private API change: `.get_serializer` now uses same `instance` and `data` ordering as serializer initialization.
 
@@ -113,8 +128,6 @@
 
 **Date**: 5th Nov 2012
 
-**Warning**: Please read [this thread][2.1.0-notes] regarding the `instance` and `data` keyword args before updating to 2.1.0.
-
 * **Serializer `instance` and `data` keyword args have their position swapped.**
 * `queryset` argument is now optional on writable model fields.
 * Hyperlinked related fields optionally take `slug_field` and `slug_url_kwarg` arguments.
@@ -123,6 +136,8 @@
 * Bugfix: Support choice field in Browseable API.
 * Bugfix: Related fields with `read_only=True` do not require a `queryset` argument.
 
+**API-incompatible changes**: Please read [this thread][2.1.0-notes] regarding the `instance` and `data` keyword args before updating to 2.1.0.
+
 ---
 
 ## 2.0.x series
@@ -159,9 +174,9 @@
 * Allow views to specify template used by TemplateRenderer
 * More consistent error responses
 * Some serializer fixes
-* Fix internet explorer ajax behaviour
+* Fix internet explorer ajax behavior
 * Minor xml and yaml fixes
-* Improve setup (eg use staticfiles, not the defunct ADMIN_MEDIA_PREFIX)
+* Improve setup (e.g. use staticfiles, not the defunct ADMIN_MEDIA_PREFIX)
 * Sensible absolute URL generation, not using hacky set_script_prefix
 
 ---
@@ -172,13 +187,13 @@
 
 * Added DjangoModelPermissions class to support `django.contrib.auth` style permissions.
 * Use `staticfiles` for css files.
-  - Easier to override.  Won't conflict with customised admin styles (eg grappelli)
+  - Easier to override.  Won't conflict with customized admin styles (e.g. grappelli)
 * Templates are now nicely namespaced.
   - Allows easier overriding.
 * Drop implied 'pk' filter if last arg in urlconf is unnamed.
-  - Too magical.  Explict is better than implicit.
-* Saner template variable autoescaping.
-* Tider setup.py
+  - Too magical.  Explicit is better than implicit.
+* Saner template variable auto-escaping.
+* Tidier setup.py
 * Updated for URLObject 2.0
 * Bugfixes:
   - Bug with PerUserThrottling when user contains unicode chars.
@@ -266,5 +281,7 @@
 * Initial release.
 
 [cite]: http://www.catb.org/~esr/writings/cathedral-bazaar/cathedral-bazaar/ar01s04.html
+[staticfiles14]: https://docs.djangoproject.com/en/1.4/howto/static-files/#with-a-template-tag
+[staticfiles13]: https://docs.djangoproject.com/en/1.3/howto/static-files/#with-a-template-tag
 [2.1.0-notes]: https://groups.google.com/d/topic/django-rest-framework/Vv2M0CMY9bg/discussion
 [announcement]: rest-framework-2-announcement.md