From bd87ba8ad04a4a743a43b9327014e7cce6cfdf57 Mon Sep 17 00:00:00 2001
From: Fabien Potencier <fabien.potencier@gmail.com>
Date: Sun, 16 Aug 2015 00:16:53 +0200
Subject: [PATCH] added some documentation about deprecation notices

---
 CHANGELOG          |  5 +++--
 doc/advanced.rst   | 17 +++++++++++++++++
 doc/deprecated.rst |  6 ++++++
 doc/recipes.rst    | 37 +++++++++++++++++++++++++++++++++++++
 4 files changed, 63 insertions(+), 2 deletions(-)

diff --git a/CHANGELOG b/CHANGELOG
index 950ea88fe6..6e5d75331c 100644
--- a/CHANGELOG
+++ b/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)
 
diff --git a/doc/advanced.rst b/doc/advanced.rst
index 6953f551bb..a20eab0348 100644
--- a/doc/advanced.rst
+++ b/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
 ---------
 
diff --git a/doc/deprecated.rst b/doc/deprecated.rst
index 84025aa34b..1489174a61 100644
--- a/doc/deprecated.rst
+++ b/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
 -------------
 
diff --git a/doc/recipes.rst b/doc/recipes.rst
index 22d44f9127..36c669d4e8 100644
--- a/doc/recipes.rst
+++ b/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
 ---------------------------