[Draft] Added detailed BC promise text

contributing/code/bc.rst

@@ -0,0 +1,188 @@
+Our Backwards Compatibility Promise
+===================================
+
+As of Symfony 2.1, we promise you backwards compatibility for all further 2.x
+releases. Ensuring smooth upgrades of your projects is our first priority.
+However, backwards compatibility comes in many different flavors. This page
+lists which code changes are covered by our promise and to what degree.
+
+If you are contributing to Symfony, make sure that your code changes comply to
+the rules listed below.
+
+.. note::
+
+    This promise is in trial until April 15th, 2014. Until then, we may change
+    parts of it if we discover problems or limitations.
+
+
+Interfaces
+----------
+
+Normal Interfaces
+~~~~~~~~~~~~~~~~~
+
+All interfaces in the ``Symfony`` namespace are **safe for use**. That means
+that:
+
+* You can safely type hint against the interface.
+
+* You can safely use any of the methods provided by the interface.
+
+However:
+
+* You cannot safely implement the interface.
+
+Methods tagged with ``@api`` are treated as if they belonged to an API
+interface.
+
+
+API Interfaces
+~~~~~~~~~~~~~~
+
+All interfaces tagged with ``@api`` are also **safe for implementation**. That
+means that:
+
+* You can safely implement the interface.
+
+
+Allowed Changes
+~~~~~~~~~~~~~~~
+
+==============================================  ==============  ==============
+Type of Change                                  Normal          API
+==============================================  ==============  ==============
+Remove entirely                                 No              No
+Change name or namespace                        No              No
+Add parent interface                            Yes [1]_        No
+Remove parent interface                         No              No
+**Methods**
+Add method                                      Yes [1]_        No
+Remove method                                   No              No
+Change name                                     No              No
+Add parameter without a default value           No              No
+Add parameter with a default value              Yes [1]_        No
+Remove parameter                                No              No
+Add default value to a parameter                Yes [1]_        No
+Remove default value of a parameter             No              No
+Add type hint to a parameter                    No              No
+Remove type hint of a parameter                 Yes [1]_        No
+Change return type                              Yes [1]_ [2]_   No
+==============================================  ==============  ==============
+
+
+Classes
+-------
+
+Normal Classes
+~~~~~~~~~~~~~~
+
+All classes in the ``Symfony`` namespace are **safe for use**. That means that:
+
+* You can safely create new instances.
+
+* You can safely extend the class.
+
+* You can safely use public properties and methods.
+
+When extending the class:
+
+* You can safely override public properties.
+
+* You cannot safely use protected properties and methods.
+
+* You cannot safely override protected properties.
+
+* You cannot safely override public or protected methods.
+
+* You cannot safely add public or protected properties, since we may add a
+  property with the same name.
+
+* You cannot safely add a new public or protected method, since we may add a
+  method with the same name.
+
+* You cannot safely add parameters to overridden methods, since we may do the
+  same.
+
+Properties and methods tagged with ``@api`` are treated as if they belonged
+to an API class.
+
+
+API Classes
+~~~~~~~~~~~
+
+All classes tagged with ``@api`` are also **safe for extension**. That means
+that:
+
+* You can safely use protected properties and methods.
+
+* You can safely override protected properties.
+
+* You can safely override public or protected methods.
+
+
+Allowed Changes
+~~~~~~~~~~~~~~~
+
+==================================================  ==============  ==============
+Type of Change                                      Normal          API
+==================================================  ==============  ==============
+Remove entirely                                     No              No
+Make final                                          Yes [1]_        No
+Make abstract                                       No              No
+Change name or namespace                            No              No
+Change parent class                                 Yes [3]_        Yes [3]_
+Add interface                                       Yes             Yes
+Remove interface                                    No              No
+**Public Properties**
+Add public property                                 Yes             Yes
+Remove public property                              No              No
+Reduce visibility                                   No              No
+**Protected Properties**
+Add protected property                              Yes             Yes
+Remove protected property                           Yes [1]_        No
+Reduce visibility                                   Yes [1]_        No
+**Constructors**
+Add constructor without mandatory parameters        Yes [1]_        Yes [1]_
+Remove constructor                                  Yes [1]_        No
+Reduce visibility of a public constructor           No              No
+Reduce visibility of a protected constructor        Yes [1]_        No
+**Public Methods**
+Add public method                                   Yes             Yes
+Remove public method                                No              No
+Change name                                         No              No
+Reduce visibility                                   No              No
+Add parameter without a default value               No              No
+Add parameter with a default value                  Yes             Yes
+Remove parameter                                    No              No
+Add default value to a parameter                    Yes [1]_        No
+Remove default value of a parameter                 No              No
+Add type hint to a parameter                        Yes [4]_        No
+Remove type hint of a parameter                     Yes [1]_        No
+Change return type                                  Yes [1]_ [2]_   No
+**Protected Methods**
+Add protected method                                Yes             Yes
+Remove protected method                             Yes [1]_        No
+Change name                                         No              No
+Reduce visibility                                   Yes [1]_        No
+Add parameter without a default value               Yes [1]_        No
+Add parameter with a default value                  Yes             Yes
+Remove parameter                                    Yes [1]_        No
+Add default value to a parameter                    Yes [1]_        No
+Remove default value of a parameter                 Yes [1]_        No
+Add type hint to a parameter                        Yes [1]_        No
+Remove type hint of a parameter                     Yes [1]_        No
+Change return type                                  Yes [1]_ [2]_   No
+==================================================  ==============  ==============
+
+
+.. [1] Should be avoided. When done, this change must be documented in the
+       UGPRADE file.
+
+.. [2] The return type may only be changed to compatible types. **TODO define
+       type compatibility**
+
+.. [3] When changing the parent class, the original parent class must remain an
+       ancestor of the class.
+
+.. [4] A type hint may only be added if using a parameter with a different type
+       previously generated a fatal error.

contributing/code/index.rst

@@ -8,6 +8,7 @@ Contributing Code
     patches
     security
     tests
+    bc
     standards
     conventions
     git

contributing/map.rst.inc

@@ -4,9 +4,10 @@
   * :doc:`Patches </contributing/code/patches>`
   * :doc:`Security </contributing/code/security>`
   * :doc:`Tests </contributing/code/tests>`
+  * :doc:`Backwards Compatibility </contributing/code/bc>`
   * :doc:`Coding Standards</contributing/code/standards>`
   * :doc:`Code Conventions</contributing/code/conventions>`
-  * :doc:`Git</contributing/code/git>`  
+  * :doc:`Git</contributing/code/git>`
   * :doc:`License </contributing/code/license>`
 
 * **Documentation**