[OptionsResolver][Config][DI] Added package and version to deprecation features

Author: wouterj

components/config/definition.rst

@@ -435,6 +435,13 @@ The following example shows these methods in practice::
 Deprecating the Option
 ----------------------
 
+.. versionadded:: 5.1
+
+    The signature of the ``setDeprecated()`` method changed from
+    ``setDeprecated(?string $message)`` to
+    ``setDeprecated(string $package, string $version, ?string $message)``
+    in Symfony 5.1.
+
 You can deprecate options using the
 :method:`Symfony\\Component\\Config\\Definition\\Builder\\NodeDefinition::setDeprecated`
 method::
@@ -443,11 +450,15 @@ method::
         ->children()
             ->integerNode('old_option')
                 // this outputs the following generic deprecation message:
-                // The child node "old_option" at path "..." is deprecated.
-                ->setDeprecated()
+                // Since acme/package 1.2: The child node "old_option" at path "..." is deprecated.
+                ->setDeprecated('acme/package', '1.2')
 
                 // you can also pass a custom deprecation message (%node% and %path% placeholders are available):
-                ->setDeprecated('The "%node%" option is deprecated. Use "new_config_option" instead.')
+                ->setDeprecated(
+                    'acme/package',
+                    '1.2',
+                    'The "%node%" option is deprecated. Use "new_config_option" instead.'
+                )
             ->end()
         ->end()
     ;

components/options_resolver.rst

@@ -720,18 +720,31 @@ In same way, parent options can access to the nested options as normal arrays::
 Deprecating the Option
 ~~~~~~~~~~~~~~~~~~~~~~
 
+.. versionadded:: 5.1
+
+    The signature of the ``setDeprecated()`` method changed from
+    ``setDeprecated(string $option, ?string $message)`` to
+    ``setDeprecated(string $option, string $package, string $version, ?string $message)``
+    in Symfony 5.1.
+
 Once an option is outdated or you decided not to maintain it anymore, you can
 deprecate it using the :method:`Symfony\\Component\\OptionsResolver\\OptionsResolver::setDeprecated`
 method::
 
     $resolver
         ->setDefined(['hostname', 'host'])
-        // this outputs the following generic deprecation message:
-        // The option "hostname" is deprecated.
-        ->setDeprecated('hostname')
 
-        // you can also pass a custom deprecation message
-        ->setDeprecated('hostname', 'The option "hostname" is deprecated, use "host" instead.')
+        // this outputs the following generic deprecation message:
+        // Since acme/package 1.2: The option "hostname" is deprecated.
+        ->setDeprecated('hostname', 'acme/package', '1.2')
+
+        // you can also pass a custom deprecation message (%name% placeholder is available)
+        ->setDeprecated(
+            'hostname',
+            'acme/package',
+            '1.2',
+            'The option "hostname" is deprecated, use "host" instead.'
+        )
     ;
 
 .. note::
@@ -756,7 +769,7 @@ the option::
         ->setDefault('encryption', null)
         ->setDefault('port', null)
         ->setAllowedTypes('port', ['null', 'int'])
-        ->setDeprecated('port', function (Options $options, $value) {
+        ->setDeprecated('port', 'acme/package', '1.2', function (Options $options, $value) {
             if (null === $value) {
                 return 'Passing "null" to option "port" is deprecated, pass an integer instead.';
             }

service_container/alias_private.rst

@@ -160,6 +160,12 @@ This means that when using the container directly, you can access the
 Deprecating Service Aliases
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
+.. versionadded:: 5.1
+
+    The ``package`` and ``version`` options were introduced in Symfony 5.1.
+    Prior to 5.1, you had to use ``deprecated: true`` or
+    ``deprecated: 'Custom message'``.
+
 If you decide to deprecate the use of a service alias (because it is outdated
 or you decided not to maintain it anymore), you can deprecate its definition:
 
@@ -170,11 +176,17 @@ or you decided not to maintain it anymore), you can deprecate its definition:
         app.mailer:
             alias: '@App\Mail\PhpMailer'
 
-            # this will display a generic deprecation message...
-            deprecated: true
+            # this outputs the following generic deprecation message:
+            # Since acme/package 1.2: The "app.mailer" service is deprecated. You should stop using it, as it will be removed in the future
+            deprecated:
+                package: 'acme/package'
+                version: '1.2'
 
-            # ...but you can also define a custom deprecation message
-            deprecated: 'The "%alias_id%" alias is deprecated. Do not use it anymore.'
+            # you can also define a custom deprecation message (%sevice_id%/%alias_id% placeholder is available)
+            deprecated:
+                package: 'acme/package'
+                version: '1.2'
+                message: 'The "%alias_id%" alias is deprecated. Do not use it anymore.'
 
     .. code-block:: xml
 
@@ -185,11 +197,14 @@ or you decided not to maintain it anymore), you can deprecate its definition:
 
             <services>
                 <service id="app.mailer" alias="App\Mail\PhpMailer">
-                    <!-- this will display a generic deprecation message... -->
-                    <deprecated/>
-
-                    <!-- ...but you can also define a custom deprecation message -->
-                    <deprecated>The "%alias_id%" service alias is deprecated. Don't use it anymore.</deprecated>
+                    <!-- this outputs the following generic deprecation message:
+                         Since acme/package 1.2: The "app.mailer" service is deprecated. You should stop using it, as it will be removed in the future -->
+                    <deprecated package="acme/package" version="1.2"/>
+
+                    <!-- you can also define a custom deprecation message (%sevice_id%/%alias_id% placeholder is available) -->
+                    <deprecated package="acme/package" version="1.2">
+                        The "%alias_id%" service alias is deprecated. Don't use it anymore.
+                    </deprecated>
                 </service>
             </services>
         </container>
@@ -199,12 +214,14 @@ or you decided not to maintain it anymore), you can deprecate its definition:
         $container
             ->setAlias('app.mailer', 'App\Mail\PhpMailer')
 
-            // this will display a generic deprecation message...
-            ->setDeprecated(true)
+            // this outputs the following generic deprecation message:
+            // Since acme/package 1.2: The "app.mailer" service is deprecated. You should stop using it, as it will be removed in the future
+            ->setDeprecated('acme/package', '1.2')
 
-            // ...but you can also define a custom deprecation message
+            // you can also define a custom deprecation message (%sevice_id%/%alias_id% placeholder is available)
             ->setDeprecated(
-                true,
+                'acme/package',
+                '1.2',
                 'The "%alias_id%" service alias is deprecated. Don\'t use it anymore.'
             )
         ;