added some documentation about deprecation notices

CHANGELOG

@@ -1,6 +1,7 @@
-* 1.20.1 (2015-XX-XX)
+* 1.21.0 (2015-XX-XX)
 
- * n/a
+ * added deprecation notices for deprecated features
+ * added a deprecation "framework" for filters/functions/tests
 
 * 1.20.0 (2015-08-12)
 

doc/advanced.rst

@@ -267,6 +267,23 @@ arguments, but after the environment and the context. For instance, a call to
 ``'foo'|a_path_b()`` will result in the following arguments to be passed to
 the filter: ``('a', 'b', 'foo')``.
 
+Deprecated Filters
+~~~~~~~~~~~~~~~~~~
+
+.. versionadded:: 1.21
+    Support for deprecated filters was added in Twig 1.21.
+
+You can mark a filter as being deprecated by setting the ``deprecated`` option
+to ``true``. You can also give an alternative filter that replaces the
+deprecated one when that makes sense::
+
+    $filter = new Twig_SimpleFilter('obsolete', function () {
+        // ...
+    }, array('deprecated' => true, 'alternative' => 'new_one'));
+
+When a filter is deprecated, Twig emits a deprecation notice when compiling a
+template using it. See :ref:`deprecation-notices` for more information.
+
 Functions
 ---------
 

doc/deprecated.rst

@@ -5,6 +5,12 @@ This document lists all deprecated features in Twig. Deprecated features are
 kept for backward compatibility and removed in the next major release (a
 feature that was deprecated in Twig 1.x is removed in Twig 2.0).
 
+Deprecation Notices
+-------------------
+
+As of Twig 1.21, Twig generates deprecation notices when a template uses
+deprecated features. See :ref:`deprecation-notices` for more information.
+
 Token Parsers
 -------------
 

doc/recipes.rst

@@ -1,6 +1,43 @@
 Recipes
 =======
 
+.. _deprecation-notices:
+
+Displaying Deprecation Notices
+------------------------------
+
+Deprecated features generate deprecation notices (via a call to the
+``trigger_error()`` PHP function). By default, they are silenced, but you can
+easily display them by registering a custom error handler like the one below::
+
+    $deprecations = array();
+    set_error_handler(function ($type, $msg) use (&$deprecations) {
+        if (E_USER_DEPRECATED === $type) {
+            $deprecations[] = $msg;
+        }
+    });
+
+    try {
+        $twig->compile($twig->parse($twig->tokenize($template)));
+    } catch (Twig_Error_Syntax $e) {
+        // $template contains one or more syntax errors
+    }
+
+    print_r($deprecations);
+
+Compile all templates with such an error handler in a script to easily remove
+all deprecated feature usages from your templates.
+
+You must be aware that most deprecation notices are triggered during
+**compilation**, so they won't be generated when templates are already cached.
+
+.. tip::
+
+    If you want to manage the deprecation notices from your PHPUnit tests, have
+    a look at the `symfony/phpunit-bridge
+    <https://github.com/symfony/phpunit-bridge>`_ package, which eases the
+    process a lot.
+
 Making a Layout conditional
 ---------------------------