Add deprecation policy to release notes.

1 files changed, 30 insertions, 4 deletions

diff --git a/docs/topics/release-notes.md b/docs/topics/release-notes.md
index 63f8539a..8756430f 100644
--- a/docs/topics/release-notes.md
+++ b/docs/topics/release-notes.md
@@ -8,9 +8,23 @@
 
 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.
+Medium version numbers (0.x.0) may include API changes, in line with the [deprecation policy][deprecation-policy].  You should read the release notes carefully before upgrading between medium point releases.
 
-Major version numbers (x.0.0) are reserved for project milestones.  No major point releases are currently planned.
+Major version numbers (x.0.0) are reserved for substantial project milestones.  No major point releases are currently planned.
+
+## Deprecation policy
+
+REST framework releases follow a formal deprecation policy, which is in line with [Django's deprecation policy][django-deprecation-policy].
+
+The timeline for deprecation of a feature present in version 1.0 would work as follows:
+
+* Version 1.1 would remain **fully backwards compatible** with 1.0, but would raise `PendingDeprecationWarning` warnings if you use the feature that are due to be deprecated.  These warnings are **silent by default**, but can be explicitly enabled when you're ready to start migrating any required changes.  For example if you start running your tests using `python -Wd manage.py test`, you'll be warned of any API changes you need to make.
+
+* Version 1.2 would escalate these warnings to `DeprecationWarning`, which is loud by default.
+
+* Version 1.3 would remove the deprecated bits of API entirely.
+
+Note that in line with Django's policy, any parts of the framework not mentioned in the documentation should generally be considered private API, and may be subject to change.
 
 ## Upgrading
 
@@ -24,9 +38,11 @@ You can determine your currently installed version using `pip freeze`:
 
 ---
 
-## 2.1.x series
+## 2.2.x series
+
+### 2.2.0
 
-### Master
+**Date**: 13th Feb 2013
 
 * Python 3 support.
 * Added a `post_save()` hook to the generic views.
@@ -35,11 +51,18 @@ You can determine your currently installed version using `pip freeze`:
 * Deprecate `null=True` on relations in favor of `required=False`.
 * Deprecate `blank=True` on CharFields, just use `required=False`.
 * Deprecate optional `obj` argument in permissions checks in favor of `has_object_permission`.
+* Deprecate implicit hyperlinked relations behavior.
 * Bugfix: Allow serializer output to be cached.
 * Bugfix: Fix styling on browsable API login.
 * Bugfix: Fix issue with deserializing empty to-many relations.
 * Bugfix: Ensure model field validation is still applied for ModelSerializer subclasses with an custom `.restore_object()` method.
 
+**Note**: See the [2.2 announcement][2.2-announcement] for full details.
+
+---
+
+## 2.1.x series
+
 ### 2.1.17
 
 **Date**: 26th Jan 2013
@@ -356,6 +379,9 @@ This change will not affect user code, so long as it's following the recommended
 * Initial release.
 
 [cite]: http://www.catb.org/~esr/writings/cathedral-bazaar/cathedral-bazaar/ar01s04.html
+[deprecation-policy]: #deprecation-policy
+[django-deprecation-policy]: https://docs.djangoproject.com/en/dev/internals/release-process/#internal-release-deprecation-policy
+[2.2-announcement]: 2.2-announcement.md
 [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