From d2cfba7e5d97fb461fe322156da5683c383b79f0 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Gr=C3=A9goire=20Paris?= Date: Fri, 3 May 2019 22:53:25 +0200 Subject: [PATCH] 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. --- contributing/code/conventions.rst | 4 ++-- contributing/code/standards.rst | 2 +- service_container/alias_private.rst | 6 +++--- 3 files changed, 6 insertions(+), 6 deletions(-) diff --git a/contributing/code/conventions.rst b/contributing/code/conventions.rst index b90cbb565da..c0a0ebe5f42 100644 --- 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 index 36278555c5d..bf683829052 100644 --- 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 index e0bf94339a9..4ca5a69891a 100644 --- 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: - 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. @@ -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.' ) ;