Add a section about how to add an argument to a method without breaking BC

Author: fabpot

contributing/code/bc.rst

@@ -334,84 +334,149 @@ Changing Traits
 This table tells you which changes you are allowed to do when working on
 Symfony's traits:
 
-==================================================  ==============  ===============
-Type of Change                                      Change Allowed  Notes
-==================================================  ==============  ===============
-Remove entirely                                     No
-Change name or namespace                            No
-Use another trait                                   Yes
+===============================================================================  ==============  ===============
+Type of Change                                                                   Change Allowed  Notes
+===============================================================================  ==============  ===============
+Remove entirely                                                                  No
+Change name or namespace                                                         No
+Use another trait                                                                Yes
 **Public Properties**
-Add public property                                 Yes
-Remove public property                              No
-Reduce visibility                                   No
-Move to a used trait                                Yes
+Add public property                                                              Yes
+Remove public property                                                           No
+Reduce visibility                                                                No
+Move to a used trait                                                             Yes
 **Protected Properties**
-Add protected property                              Yes
-Remove protected property                           No
-Reduce visibility                                   No
-Make public                                         No
-Move to a used trait                                Yes
+Add protected property                                                           Yes
+Remove protected property                                                        No
+Reduce visibility                                                                No
+Make public                                                                      No
+Move to a used trait                                                             Yes
 **Private Properties**
-Add private property                                Yes
-Remove private property                             No
-Make public or protected                            Yes
-Move to a used trait                                Yes
+Add private property                                                             Yes
+Remove private property                                                          No
+Make public or protected                                                         Yes
+Move to a used trait                                                             Yes
 **Constructors and destructors**
-Have constructor or destructor                      No
+Have constructor or destructor                                                   No
 **Public Methods**
-Add public method                                   Yes
-Remove public method                                No
-Change name                                         No
-Reduce visibility                                   No
-Make final                                          No              :ref:`[6] <note-6>`
-Move to used trait                                  Yes
-Add argument without a default value                No
-Add argument with a default value                   No
-Remove argument                                     No
-Add default value to an argument                    No
-Remove default value of an argument                 No
-Add type hint to an argument                        No
-Remove type hint of an argument                     No
-Change argument type                                No
-Change return type                                  No
+Add public method                                                                Yes
+Remove public method                                                             No
+Change name                                                                      No
+Reduce visibility                                                                No
+Make final                                                                       No              :ref:`[6] <note-6>`
+Move to used trait                                                               Yes
+:ref:`Add argument with a default value <add-argument-public-method>`            No
+:ref:`Add argument with a default value <add-argument-public-method>`            No
+Remove argument                                                                  No
+Add default value to an argument                                                 No
+Remove default value of an argument                                              No
+Add type hint to an argument                                                     No
+Remove type hint of an argument                                                  No
+Change argument type                                                             No
+Change return type                                                               No
 **Protected Methods**
-Add protected method                                Yes
-Remove protected method                             No
-Change name                                         No
-Reduce visibility                                   No
-Make final                                          No              :ref:`[6] <note-6>`
-Make public                                         No              :ref:`[8] <note-8>`
-Move to used trait                                  Yes
-Add argument without a default value                No
-Add argument with a default value                   No
-Remove argument                                     No
-Add default value to an argument                    No
-Remove default value of an argument                 No
-Add type hint to an argument                        No
-Remove type hint of an argument                     No
-Change argument type                                No
-Change return type                                  No
+Add protected method                                                             Yes
+Remove protected method                                                          No
+Change name                                                                      No
+Reduce visibility                                                                No
+Make final                                                                       No              :ref:`[6] <note-6>`
+Make public                                                                      No              :ref:`[8] <note-8>`
+Move to used trait                                                               Yes
+Add argument without a default value                                             No
+Add argument with a default value                                                No
+Remove argument                                                                  No
+Add default value to an argument                                                 No
+Remove default value of an argument                                              No
+Add type hint to an argument                                                     No
+Remove type hint of an argument                                                  No
+Change argument type                                                             No
+Change return type                                                               No
 **Private Methods**
-Add private method                                  Yes
-Remove private method                               No
-Change name                                         No
-Make public or protected                            Yes
-Move to used trait                                  Yes
-Add argument without a default value                No
-Add argument with a default value                   No
-Remove argument                                     No
-Add default value to an argument                    No
-Remove default value of an argument                 No
-Add type hint to an argument                        No
-Remove type hint of an argument                     No
-Change argument type                                No
-Add return type                                     No
-Remove return type                                  No
-Change return type                                  No
-**Static Methods and Properties**
-Turn non static into static                         No
-Turn static into non static                         No
-==================================================  ==============  ===============
+Add private method                                                               Yes
+Remove private method                                                            No
+Change name                                                                      No
+Make public or protected                                                         Yes
+Move to used trait                                                               Yes
+Add argument without a default value                                             No
+Add argument with a default value                                                No
+Remove argument                                                                  No
+Add default value to an argument                                                 No
+Remove default value of an argument                                              No
+Add type hint to an argument                                                     No
+Remove type hint of an argument                                                  No
+Change argument type                                                             No
+Add return type                                                                  No
+Remove return type                                                               No
+Change return type                                                               No
+**Static Methods and Properties**          
+Turn non static into static                                                      No
+Turn static into non static                                                      No
+===============================================================================  ==============  ===============
+
+Making Code Changes in a Backward Compatible Way
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+As you read above, many changes are not allowed because they would represent a
+backward compability break. However, we want to be able to improve the code and
+its features over time and that can nbe done thanks to some strategies that
+allow to still do some unallowed changes in several steps that ensure backward
+compability and a smooth upgrade path. Some of them are described in the next
+sections.
+
+.. _add-argument-public-method:
+
+Adding an Argument to a Public Method
+.....................................
+
+Adding a new argument to a public method is possible only if this is the last
+argument of the method.
+
+If that's the case, here is how to do it properly in a minor version:
+
+#. Add the argument as a comment in the signature::
+
+        // the new argument can be optional
+        public function say(string $text, /* bool $stripWithespace = true */): void
+        {
+        }
+
+        // or required
+        public function say(string $text, /* bool $stripWithespace */): void
+        {
+        }
+
+#. Document the new argument in a PHPDoc::
+
+        /**
+         * @param bool $stripWithespace
+         */
+
+#. Use ``func_num_args`` and ``func_get_arg`` to retrieve the argument in the
+   method::
+
+        $stripWithespace = 2 <= \func_num_args() ? func_get_arg(1) : false;
+
+    Note that the default value is ``false`` to keep the current behavior.
+
+#. If the argument has a default value that will change the current behavior,
+   warn the user::
+
+        trigger_deprecation('symfony/COMPONENT', 'X.Y', 'Not passing the "bool $stripWithespace" argument explicitly is deprecated, its default value will change to X in Z.0.');
+
+#. If the argument has no default value, warn the user that is going to be
+   required in the next major version::
+
+        if (\func_num_args() < 2) {
+            trigger_deprecation('symfony/COMPONENT', 'X.Y', 'The "%s()" method will have a new "bool $stripWithespace" argument in version Z.0, not defining it is deprecated.', __METHOD__);
+
+            $stripWithespace = false;
+        } else {
+            $stripWithespace = func_get_arg(1);
+        }
+
+5/ In the next major version (``X.0``), uncomment the argument, remove the
+PHPDoc if there is no need for a description, and remove the ``func_get_arg``
+code and the warning if any.
 
 Notes
 ~~~~~