From b65ecf48278c75f255871bae530904bc34b6f731 Mon Sep 17 00:00:00 2001
From: Andrew Svetlov <andrew.svetlov@gmail.com>
Date: Sat, 19 Nov 2016 19:52:15 +0200
Subject: [PATCH] Add a FAQ chapter for deprecation policy

---
 docs/changes.rst |  2 ++
 docs/faq.rst     | 21 +++++++++++++++++++++
 2 files changed, 23 insertions(+)

diff --git a/docs/changes.rst b/docs/changes.rst
index 50ad8f4db59..005bd1fdc38 100644
--- a/docs/changes.rst
+++ b/docs/changes.rst
@@ -1,3 +1,5 @@
+.. _aiohttp_changes:
+
 .. include:: ../CHANGES.rst
 
 .. include:: ../HISTORY.rst
diff --git a/docs/faq.rst b/docs/faq.rst
index 653e96fade0..853c62214db 100644
--- a/docs/faq.rst
+++ b/docs/faq.rst
@@ -315,5 +315,26 @@ Note how we are using the ``side_effect`` feature for injecting the loop to the
 ``AioESService.__init__`` call. The use of ``**args, **kwargs`` is mandatory
 in order to propagate the arguments being used by the caller.
 
+
+API stability and deprecation policy
+------------------------------------
+
+aiohttp tries to not break existing users code.
+
+Obsolete attributes and methods are marked as *deprecated* in
+documentation and raises :class:`DeprecationWarning` on usage.
+
+Deprecation period is usually a year and half.
+
+After the period is passed out deprecated code is be removed.
+
+Unfortunately we should break own rules if new functionality or bug
+fixing forces us to do it (for example proper cookies support on
+client side forced us to break backward compatibility twice).
+
+All *backward incompatible* changes are explicitly marked in
+:ref:`CHANGES <aiohttp_changes>` chapter.
+
+
 .. disqus::
   :title: aiohttp FAQ