Fix doc about deprecations policy

Author: nicolas-grekas

Diff for: contributing/code/conventions.rst

@@ -103,4 +103,9 @@ 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.X and will be removed in 2.Y. Use XXX instead.', E_USER_DEPRECATED);
+
+Without the @-silencing operator, 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 the PHPUnit bridge.)

Diff for: cookbook/upgrade/major_version.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,9 +35,9 @@ 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
@@ -52,7 +52,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: