Fix doc about deprecations policy

Author: nicolas-grekas

Diff for: contributing/code/conventions.rst

@@ -92,7 +92,7 @@ A feature is marked as deprecated by adding a ``@deprecated`` phpdoc to
 relevant classes, methods, properties, ...::
 
     /**
-     * @deprecated Deprecated since version 2.X, to be removed in 2.Y. Use XXX instead.
+     * @deprecated Deprecated since version 2.8, to be removed in 3.0. Use XXX instead.
      */
 
 The deprecation message should indicate the version when the class/method was
@@ -103,4 +103,10 @@ A PHP ``E_USER_DEPRECATED`` error must also be triggered to help people with
 the migration starting one or two minor versions before the version where the
 feature will be removed (depending on the criticality of the removal)::
 
-    trigger_error('XXX() is deprecated since version 2.X and will be removed in 2.Y. Use XXX instead.', E_USER_DEPRECATED);
+    @trigger_error('XXX() is deprecated since version 2.8 and will be removed in 3.0. Use XXX instead.', E_USER_DEPRECATED);
+
+Without the `@-silencing operator <https://php.net/manual/en/language.operators.errorcontrol.php>`_,
+users would need to opt-out from deprecation notices. Silencing swaps this
+behavior and allows users to opt-in when they are ready to cope with them
+(by adding a custom error handler like the one used by the Web Debug Toolbar or
+by the PHPUnit bridge.)

Diff for: cookbook/map.rst.inc

@@ -224,7 +224,6 @@
   * :doc:`/cookbook/upgrade/patch_version`
   * :doc:`/cookbook/upgrade/minor_version`
   * :doc:`/cookbook/upgrade/major_version`
-  * :doc:`/cookbook/upgrade/deprecation_warnings`
 
 * :doc:`/cookbook/validation/index`
 

Diff for: cookbook/upgrade/deprecation_warnings.rst

@@ -16,4 +16,3 @@ There are three types of upgrades, all needing a little different preparation:
     /cookbook/upgrade/patch_version
     /cookbook/upgrade/minor_version
     /cookbook/upgrade/major_version
-    /cookbook/upgrade/deprecation_warnings

Diff for: cookbook/upgrade/index.rst

@@ -26,7 +26,7 @@ There are a couple of steps to upgrading a major version:
 During the lifecycle of a major release, new features are added and method
 signatures and public API usages are changed. However,
 :doc:`minor versions </cookbook/upgrade/minor_version>` should not contain any
-backwards compatibility changes. To accomplish this, the "old" (e.g. functions,
+backwards incompatible changes. To accomplish this, the "old" (e.g. functions,
 classes, etc) code still works, but is marked as *deprecated*, indicating that
 it will be removed/changed in the future and that you should stop using it.
 
@@ -35,13 +35,27 @@ functionality are removed. So, as long as you've updated your code to stop
 using these deprecated features in the last version before the major (e.g.
 2.8.*), you should be able to upgrade without a problem.
 
-To help you with this, the last minor releases will trigger deprecated notices.
-For example, 2.7 and 2.8 trigger deprecated notices. When visiting your
-application in the :doc:`dev environment </cookbook/configuration/environments>`
+To help you with this, deprecation notices are triggered whenever you end up
+using a deprecated feature. When visiting your application in the
+:doc:`dev environment </cookbook/configuration/environments>`
 in your browser, these notices are shown in the web dev toolbar:
 
 .. image:: /images/cookbook/deprecations-in-profiler.png
 
+Of course ultimately, you want to stop using the deprecated functionality.
+Sometimes, this is easy: the warning might tell you exactly what to change.
+
+But other times, the warning might be unclear: a setting somewhere might
+cause a class deeper to trigger the warning. In this case, Symfony does its
+best to give a clear message, but you may need to research that warning further.
+
+And sometimes, the warning may come from a third-party library or bundle
+that you're using. If that's true, there's a good chance that those deprecations
+have already been updated. In that case, upgrade the library to fix them.
+
+Once all the deprecation warnings are gone, you can upgrade with a lot
+more confidence.
+
 Deprecations in PHPUnit
 ~~~~~~~~~~~~~~~~~~~~~~~
 
@@ -52,7 +66,7 @@ To make sure this doesn't happen, you can install the PHPUnit bridge:
 
 .. code-block:: bash
 
-    $ composer require symfony/phpunit-bridge
+    $ composer require --dev symfony/phpunit-bridge
 
 Now, your tests execute normally and a nice summary of the deprecation notices
 is displayed at the end of the test report: