minor #11522 Recommend including the package name in messages (greg0ire)

javiereguiluz · javiereguiluz · commit c0a88f6ad089 · 2019-05-06T08:47:55.000+02:00
This PR was merged into the 3.4 branch. Discussion ---------- Recommend including the package name in messages Version numbers, but they make more sense when you know the package name. Most times, you will be able to figure it out from some FQCN, but this should make things easier for everyone. cc @nicolas-grekas who told me about this best practice I'm unsure about whether this is the best branch for that kind of (pedantic ?) change Commits ------- d2cfba7 Recommend including the package name in messages
diff --git a/contributing/code/conventions.rst b/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 since version 2.8, to be removed in 3.0. Use XXX instead.
+     * @deprecated since foo-org/bar-lib 2.8, to be removed in 3.0. Use XXX instead.
      */
 
 The deprecation message should indicate the version when the class/method was
@@ -103,7 +103,7 @@ 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.8 and will be removed in 3.0. Use XXX instead.', E_USER_DEPRECATED);
+    @trigger_error('XXX() is deprecated since foo-org/bar-lib 2.8 and will be removed in 3.0. 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
diff --git a/contributing/code/standards.rst b/contributing/code/standards.rst
@@ -67,7 +67,7 @@ short example containing most features described below::
          */
         public function someDeprecatedMethod()
         {
-            @trigger_error(sprintf('The %s() method is deprecated since version 2.8 and will be removed in 3.0. Use Acme\Baz::someMethod() instead.', __METHOD__), E_USER_DEPRECATED);
+            @trigger_error(sprintf('The %s() method is deprecated since foo-org/bar-lib 2.8 and will be removed in 3.0. Use Acme\Baz::someMethod() instead.', __METHOD__), E_USER_DEPRECATED);
 
             return Baz::someMethod();
         }
diff --git a/service_container/alias_private.rst b/service_container/alias_private.rst
@@ -241,7 +241,7 @@ or you decided not to maintain it anymore), you can deprecate its definition:
     .. code-block:: yaml
 
         AppBundle\Service\OldService:
-            deprecated: The "%service_id%" service is deprecated since 2.8 and will be removed in 3.0.
+            deprecated: The "%service_id%" service is deprecated since foo-org/bar-bundle 2.8 and will be removed in 3.0.
 
     .. code-block:: xml
 
@@ -252,7 +252,7 @@ or you decided not to maintain it anymore), you can deprecate its definition:
 
             <services>
                 <service id="AppBundle\Service\OldService">
-                    <deprecated>The "%service_id%" service is deprecated since 2.8 and will be removed in 3.0.</deprecated>
+                    <deprecated>The "%service_id%" service is deprecated since foo-org/bar-bundle 2.8 and will be removed in 3.0.</deprecated>
                 </service>
             </services>
         </container>
@@ -265,7 +265,7 @@ or you decided not to maintain it anymore), you can deprecate its definition:
             ->register(OldService::class)
             ->setDeprecated(
                 true,
-                'The "%service_id%" service is deprecated since 2.8 and will be removed in 3.0.'
+                'The "%service_id%" service is deprecated since foo-org/bar-bundle 2.8 and will be removed in 3.0.'
             )
         ;
 

Original file line number	Diff line number	Diff line change
`@@ -67,7 +67,7 @@ short example containing most features described below::`
`67`	`67`	`*/`
`68`	`68`	`public function someDeprecatedMethod()`
`69`	`69`	`{`
`70`		`- @trigger_error(sprintf('The %s() method is deprecated since version 2.8 and will be removed in 3.0. Use Acme\Baz::someMethod() instead.', __METHOD__), E_USER_DEPRECATED);`
	`70`	`+ @trigger_error(sprintf('The %s() method is deprecated since foo-org/bar-lib 2.8 and will be removed in 3.0. Use Acme\Baz::someMethod() instead.', __METHOD__), E_USER_DEPRECATED);`
`71`	`71`
`72`	`72`	`return Baz::someMethod();`
`73`	`73`	`}`