[DependencyInjection] Enable deprecating parameters

Author: alexandre-daubois

configuration.rst

@@ -58,7 +58,7 @@ Configuration Formats
 ~~~~~~~~~~~~~~~~~~~~~
 
 Unlike other frameworks, Symfony doesn't impose a specific format on you to
-configure your applications, but lets you choose between YAML, XML and PHP. 
+configure your applications, but lets you choose between YAML, XML and PHP.
 Throughout the Symfony documentation, all configuration examples will be
 shown in these three formats.
 

service_container.rst

@@ -607,6 +607,23 @@ accessor methods for parameters::
     To learn more about compiling the container see
     :doc:`/components/dependency_injection/compilation`.
 
+It is also possible to deprecate a container parameter. This is particularly useful
+if you're writing your own package and want to warn developers to not use a parameter anymore
+because it will be removed in one of the next version of your package.
+Deprecating a container parameter can be done as follow::
+
+    $container->deprecateParameter(
+        'vendor.database_user',
+        'vendor-name/package-name',
+        '1.3',
+        // optionally you can set a custom deprecation message
+        '"vendor.database_user" is deprecated, you should configure database credentials in "vendor.database_dsn" parameter instead.'
+    );
+
+.. versionadded:: 6.3
+
+    The ``ContainerBuilder::deprecateParameter`` method was introduced in Symfony 6.3.
+
 .. _services-wire-specific-service:
 
 Choose a Specific Service