Add a FAQ chapter for deprecation policy

pawelmhm · Nov 19, 2016 · b65ecf4 · b65ecf4
1 parent 3dc746c
commit b65ecf4
Show file tree

Hide file tree

Showing 2 changed files with 23 additions and 0 deletions.
diff --git 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
@@ -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