[symfony#13379] Some small cleanups

Author: wouterj

Diff for: components/phpunit_bridge.rst

@@ -161,11 +161,14 @@ each test suite's results in their own section.
 Trigger Deprecation Notices
 ---------------------------
 
-Deprecation notices can be triggered by using::
+Deprecation notices can be triggered by using ``trigger_deprecation`` from
+the ``symfony/deprecation-contracts`` package::
 
-    trigger_deprecation('vendor-name/package-name', '5.1', 'Your deprecation message');
+    // indicates something is deprecated since version 1.3 of vendor-name/packagename
+    trigger_deprecation('vendor-name/package-name', '1.3', 'Your deprecation message');
 
-Where 5.1 is the version from which the deprecation starts. Note that the deprecation message can use the :phpfunction:`printf` format. In this case, you can pass placeholders as extra arguments after the deprecation message.
+    // you can also use printf format (all arguments after the message will be used)
+    trigger_deprecation('...', '1.3', 'Value "%s" is deprecated, use ...  instead.', $value);
 
 Mark Tests as Legacy
 --------------------

Diff for: contributing/code/conventions.rst

@@ -116,12 +116,10 @@ When the replacement is in another namespace than the deprecated class, its FQCN
      * @deprecated since Symfony 5.1, use A\B\Replacement instead.
      */
 
-A PHP ``E_USER_DEPRECATED`` error must also be triggered to help people with the migration::
-
-    trigger_deprecation('vendor-name/package-name', '5.1', 'The "%s" class is deprecated since Symfony 5.1, use "%s" instead.', Deprecated::class, Replacement::class);
-
-The ``trigger_deprecation`` function internally use the php function :phpfunction:`assert`. This means you should use `zend.assertions` to disable deprecations in production.
+A deprecation must also be triggered to help people with the migration
+(requires the ``symfony/deprecation-contracts`` package)::
 
+    trigger_deprecation('symfony/package-name', '5.1', 'The "%s" class is deprecated, use "%s" instead.', Deprecated::class, Replacement::class);
 
 When deprecating a whole class the ``trigger_deprecation()`` call should be placed
 between the namespace and the use declarations, like in this example from
@@ -131,7 +129,7 @@ between the namespace and the use declarations, like in this example from
 
     use Symfony\Component\Routing\Loader\ContainerLoader;
 
-    trigger_deprecation('symfony/routing', '4.4', 'The "%s" class is deprecated since Symfony 4.4, use "%s" instead.', ServiceRouterLoader::class, ContainerLoader::class);
+    trigger_deprecation('symfony/routing', '4.4', 'The "%s" class is deprecated, use "%s" instead.', ServiceRouterLoader::class, ContainerLoader::class);
 
     /**
      * @deprecated since Symfony 4.4, use Symfony\Component\Routing\Loader\ContainerLoader instead.

Diff for: contributing/code/standards.rst

@@ -72,7 +72,7 @@ short example containing most features described below::
          */
         public function someDeprecatedMethod()
         {
-            trigger_deprecation('vendor-name/package-name', '5.1', 'The %s() method is deprecated. Use Acme\Baz::someMethod() instead.', __METHOD__);
+            trigger_deprecation('symfony/package-name', '5.1', 'The %s() method is deprecated, use Acme\Baz::someMethod() instead.', __METHOD__);
 
             return Baz::someMethod();
         }