From 840073ca5c97006dcc008a6ba6932c73ab6ee177 Mon Sep 17 00:00:00 2001 From: Bernhard Schussek Date: Tue, 7 Jan 2014 12:39:31 +0100 Subject: [PATCH 01/39] Added detailed BC promise text --- contributing/code/bc.rst | 191 ++++++++++++++++++++++++++++++++++++ contributing/code/index.rst | 1 + contributing/map.rst.inc | 3 +- 3 files changed, 194 insertions(+), 1 deletion(-) create mode 100644 contributing/code/bc.rst diff --git a/contributing/code/bc.rst b/contributing/code/bc.rst new file mode 100644 index 00000000000..cf43865f818 --- /dev/null +++ b/contributing/code/bc.rst @@ -0,0 +1,191 @@ +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. The interface may change, but all + changes will be documented in the UPGRADE file. + +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. We may change or + remove them, but will document this in the UPGRADE file. + +* You cannot safely override protected properties. We may change or + remove them, but will document this in the UPGRADE file. + +* You cannot safely override public or protected methods. We may change them, + but will document this in the UPGRADE file. + +* You cannot safely add public or protected properties. We may add a property + with the same name. + +* You cannot safely add a new public or protected method. We may add a method + with the same name. + +* You cannot safely add parameters to overridden methods. 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 passing a value with a different type + previously generated a fatal error. diff --git a/contributing/code/index.rst b/contributing/code/index.rst index a675e00f2ce..7a8e7d38476 100644 --- a/contributing/code/index.rst +++ b/contributing/code/index.rst @@ -8,6 +8,7 @@ Contributing Code patches security tests + bc standards conventions git diff --git a/contributing/map.rst.inc b/contributing/map.rst.inc index 62a5e9f2f9e..13cd0d41c12 100644 --- a/contributing/map.rst.inc +++ b/contributing/map.rst.inc @@ -4,9 +4,10 @@ * :doc:`Patches ` * :doc:`Security ` * :doc:`Tests ` + * :doc:`Backwards Compatibility ` * :doc:`Coding Standards` * :doc:`Code Conventions` - * :doc:`Git` + * :doc:`Git` * :doc:`License ` * **Documentation** From 7320ed0c44784da8864d0f6cea08bed807e9cea2 Mon Sep 17 00:00:00 2001 From: Bernhard Schussek Date: Tue, 7 Jan 2014 15:24:13 +0100 Subject: [PATCH 02/39] Updated BC promise to be valid as of Symfony 2.3 --- contributing/code/bc.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/contributing/code/bc.rst b/contributing/code/bc.rst index cf43865f818..e37007c6aea 100644 --- a/contributing/code/bc.rst +++ b/contributing/code/bc.rst @@ -1,7 +1,7 @@ Our Backwards Compatibility Promise =================================== -As of Symfony 2.1, we promise you backwards compatibility for all further 2.x +As of Symfony 2.3, 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. From dacd7ce77d5969bf176e712a947c3a8cce5c611d Mon Sep 17 00:00:00 2001 From: Bernhard Schussek Date: Tue, 7 Jan 2014 15:39:58 +0100 Subject: [PATCH 03/39] Rearranged rules to be more easily understandable --- contributing/code/bc.rst | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/contributing/code/bc.rst b/contributing/code/bc.rst index e37007c6aea..0edfa242f81 100644 --- a/contributing/code/bc.rst +++ b/contributing/code/bc.rst @@ -87,13 +87,13 @@ All classes in the ``Symfony`` namespace are **safe for use**. That means that: When extending the class: -* You can safely override public properties. - * You cannot safely use protected properties and methods. We may change or remove them, but will document this in the UPGRADE file. -* You cannot safely override protected properties. We may change or - remove them, but will document this in the UPGRADE file. +* You can safely override public properties. + +* You cannot safely override protected properties. We may change or remove them, + but will document this in the UPGRADE file. * You cannot safely override public or protected methods. We may change them, but will document this in the UPGRADE file. From 79ca9f76477c9becbb1546ddd96d9ce66b2c840f Mon Sep 17 00:00:00 2001 From: Bernhard Schussek Date: Wed, 8 Jan 2014 10:15:47 +0100 Subject: [PATCH 04/39] Added information about type compatibility --- contributing/code/bc.rst | 27 +++++++++++++++++++++++++-- 1 file changed, 25 insertions(+), 2 deletions(-) diff --git a/contributing/code/bc.rst b/contributing/code/bc.rst index 0edfa242f81..e6d98d1438e 100644 --- a/contributing/code/bc.rst +++ b/contributing/code/bc.rst @@ -181,11 +181,34 @@ 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** +.. [2] The return type may only be changed to compatible types. The following + type changes are allowed: + + =================== ================================================================== + Original Type New Type + =================== ================================================================== + boolean any `scalar type`_ with equivalent `boolean values`_ + string any `scalar type`_ or object with equivalent `string values`_ + integer any `scalar type`_ with equivalent `integer values`_ + float any `scalar type`_ with equivalent `float values`_ + array instance of ``ArrayAccess``, ``Traversable`` and ``Countable`` + ``ArrayAccess`` array + ``Traversable`` array + ``Countable`` array + =================== ================================================================== .. [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 passing a value with a different type previously generated a fatal error. + +.. _scalar type: http://php.net/manual/en/function.is-scalar.php + +.. _boolean values: http://php.net/manual/en/function.boolval.php + +.. _string values: http://www.php.net/manual/en/function.strval.php + +.. _integer values: http://www.php.net/manual/en/function.intval.php + +.. _float values: http://www.php.net/manual/en/function.floatval.php From 0e925cb522627d8acbcd75761d7132c33680c3e3 Mon Sep 17 00:00:00 2001 From: Bernhard Schussek Date: Wed, 8 Jan 2014 10:41:52 +0100 Subject: [PATCH 05/39] Added tables with safe operations --- contributing/code/bc.rst | 52 ++++++++++++++++++++++++++++++++++++++++ 1 file changed, 52 insertions(+) diff --git a/contributing/code/bc.rst b/contributing/code/bc.rst index e6d98d1438e..c94a4ed90b8 100644 --- a/contributing/code/bc.rst +++ b/contributing/code/bc.rst @@ -46,9 +46,30 @@ means that: * You can safely implement the interface. +Safe Operations +~~~~~~~~~~~~~~~ + +The following table summarizes the safe operations when using our interfaces: + +============================================== ============== ============== +Operation Normal API +============================================== ============== ============== +Type hint against Safe Safe +Use method Safe Safe +**When Implementing** +Implement method Not Safe Safe +Add custom method Not Safe Not Safe +Add custom method parameter Not Safe Not Safe +Add parameter default value Safe Safe +============================================== ============== ============== + + Allowed Changes ~~~~~~~~~~~~~~~ +This table tells you which changes you are allowed to do when working on +Symfony code: + ============================================== ============== ============== Type of Change Normal API ============================================== ============== ============== @@ -79,6 +100,8 @@ Normal Classes All classes in the ``Symfony`` namespace are **safe for use**. That means that: +* You can safely type hint against the class' name. + * You can safely create new instances. * You can safely extend the class. @@ -123,9 +146,38 @@ that: * You can safely override public or protected methods. +Safe Operations +~~~~~~~~~~~~~~~ + +The following table summarizes the safe operations when using our classes: + +============================================== ============== ============== +Operation Normal API +============================================== ============== ============== +Type hint against Safe Safe +Create instance Safe Safe +Extend Safe Safe +Use public property Safe Safe +Use protected property Not Safe Safe +Use public method Safe Safe +Use protected method Not Safe Safe +**When Extending** +Override public property Safe Safe +Override protected property Not Safe Safe +Override public method Not Safe Safe +Override protected method Not Safe Safe +Add custom method Not Safe Not Safe +Add custom method parameter Not Safe Not Safe +Add parameter default value Safe Safe +============================================== ============== ============== + + Allowed Changes ~~~~~~~~~~~~~~~ +This table tells you which changes you are allowed to do when working on +Symfony code: + ================================================== ============== ============== Type of Change Normal API ================================================== ============== ============== From 44ecf16cfabfd25171d4c3d3c57544b625ac8f76 Mon Sep 17 00:00:00 2001 From: Bernhard Schussek Date: Wed, 8 Jan 2014 10:47:31 +0100 Subject: [PATCH 06/39] Fixed: No parameters must be added (ever) to API class methods --- contributing/code/bc.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/contributing/code/bc.rst b/contributing/code/bc.rst index c94a4ed90b8..b021f016841 100644 --- a/contributing/code/bc.rst +++ b/contributing/code/bc.rst @@ -207,7 +207,7 @@ 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 +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 @@ -220,7 +220,7 @@ 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 +Add parameter with a default value Yes [1]_ No Remove parameter Yes [1]_ No Add default value to a parameter Yes [1]_ No Remove default value of a parameter Yes [1]_ No From afadaabf984a94faebfa463e7097183d74239aa5 Mon Sep 17 00:00:00 2001 From: Bernhard Schussek Date: Wed, 8 Jan 2014 10:54:30 +0100 Subject: [PATCH 07/39] Changed: The last parameters of a method may be removed --- contributing/code/bc.rst | 24 +++++++++++++----------- 1 file changed, 13 insertions(+), 11 deletions(-) diff --git a/contributing/code/bc.rst b/contributing/code/bc.rst index b021f016841..a5746e5df7d 100644 --- a/contributing/code/bc.rst +++ b/contributing/code/bc.rst @@ -83,12 +83,12 @@ 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 +Remove parameter Yes [2]_ Yes [2]_ 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 +Change return type Yes [1]_ [3]_ No ============================================== ============== ============== @@ -185,7 +185,7 @@ 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]_ +Change parent class Yes [4]_ Yes [4]_ Add interface Yes Yes Remove interface No No **Public Properties** @@ -208,12 +208,12 @@ Change name No No Reduce visibility No No Add parameter without a default value No No Add parameter with a default value Yes [1]_ No -Remove parameter No No +Remove parameter Yes [2]_ Yes [2]_ 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 +Add type hint to a parameter Yes [5]_ No Remove type hint of a parameter Yes [1]_ No -Change return type Yes [1]_ [2]_ No +Change return type Yes [1]_ [3]_ No **Protected Methods** Add protected method Yes Yes Remove protected method Yes [1]_ No @@ -221,19 +221,21 @@ 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 [1]_ No -Remove parameter Yes [1]_ No +Remove parameter Yes [2]_ Yes [2]_ 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 +Change return type Yes [1]_ [3]_ 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. The following +.. [2] Only the last parameter(s) of a method may be removed. + +.. [3] The return type may only be changed to compatible types. The following type changes are allowed: =================== ================================================================== @@ -249,10 +251,10 @@ Change return type Yes [1]_ [2]_ No ``Countable`` array =================== ================================================================== -.. [3] When changing the parent class, the original parent class must remain an +.. [4] 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 passing a value with a different type +.. [5] A type hint may only be added if passing a value with a different type previously generated a fatal error. .. _scalar type: http://php.net/manual/en/function.is-scalar.php From 345410cfe529e18adbb9b35aa5dce700645b940f Mon Sep 17 00:00:00 2001 From: Bernhard Schussek Date: Wed, 8 Jan 2014 10:56:39 +0100 Subject: [PATCH 08/39] Rearranged safe operations to make more sense --- contributing/code/bc.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/contributing/code/bc.rst b/contributing/code/bc.rst index a5746e5df7d..18a584865dc 100644 --- a/contributing/code/bc.rst +++ b/contributing/code/bc.rst @@ -158,10 +158,10 @@ Type hint against Safe Safe Create instance Safe Safe Extend Safe Safe Use public property Safe Safe -Use protected property Not Safe Safe Use public method Safe Safe -Use protected method Not Safe Safe **When Extending** +Use protected property Not Safe Safe +Use protected method Not Safe Safe Override public property Safe Safe Override protected property Not Safe Safe Override public method Not Safe Safe From a3ad08cecb518c229a9f91ef16696aa30355b58c Mon Sep 17 00:00:00 2001 From: Bernhard Schussek Date: Wed, 8 Jan 2014 10:59:42 +0100 Subject: [PATCH 09/39] Removed most of the "cannot" statements which are repeated in the tables now --- contributing/code/bc.rst | 18 +++--------------- 1 file changed, 3 insertions(+), 15 deletions(-) diff --git a/contributing/code/bc.rst b/contributing/code/bc.rst index 18a584865dc..516c3d5614e 100644 --- a/contributing/code/bc.rst +++ b/contributing/code/bc.rst @@ -110,24 +110,12 @@ All classes in the ``Symfony`` namespace are **safe for use**. That means that: When extending the class: -* You cannot safely use protected properties and methods. We may change or - remove them, but will document this in the UPGRADE file. - * You can safely override public properties. -* You cannot safely override protected properties. We may change or remove them, - but will document this in the UPGRADE file. - -* You cannot safely override public or protected methods. We may change them, - but will document this in the UPGRADE file. - -* You cannot safely add public or protected properties. We may add a property - with the same name. - -* You cannot safely add a new public or protected method. We may add a method - with the same name. +However: -* You cannot safely add parameters to overridden methods. We may do the same. +* You cannot safely override methods in extending classes. The class may change, + but all changes will be documented in the UPGRADE file. Properties and methods tagged with ``@api`` are treated as if they belonged to an API class. From 31ab2dbd554904acb45d7c76a79a0613495b7920 Mon Sep 17 00:00:00 2001 From: Bernhard Schussek Date: Wed, 8 Jan 2014 11:05:47 +0100 Subject: [PATCH 10/39] Improved wording --- contributing/code/bc.rst | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/contributing/code/bc.rst b/contributing/code/bc.rst index 516c3d5614e..4e51c6cc4d3 100644 --- a/contributing/code/bc.rst +++ b/contributing/code/bc.rst @@ -67,8 +67,8 @@ Add parameter default value Safe Safe Allowed Changes ~~~~~~~~~~~~~~~ -This table tells you which changes you are allowed to do when working on -Symfony code: +This table tells you which changes you are allowed to do when working on the +code of Symfony's interfaces: ============================================== ============== ============== Type of Change Normal API @@ -163,8 +163,8 @@ Add parameter default value Safe Safe Allowed Changes ~~~~~~~~~~~~~~~ -This table tells you which changes you are allowed to do when working on -Symfony code: +This table tells you which changes you are allowed to do when working on the +code of Symfony's classes ================================================== ============== ============== Type of Change Normal API From 502ed954fb6171aa529c8fb68f570c16533b87cd Mon Sep 17 00:00:00 2001 From: Bernhard Schussek Date: Wed, 8 Jan 2014 11:13:22 +0100 Subject: [PATCH 11/39] Added: Some breaking changes to unsafe operations are documented in the UPGRADE file --- contributing/code/bc.rst | 85 +++++++++++++++++++++------------------- 1 file changed, 44 insertions(+), 41 deletions(-) diff --git a/contributing/code/bc.rst b/contributing/code/bc.rst index 4e51c6cc4d3..5949c27408f 100644 --- a/contributing/code/bc.rst +++ b/contributing/code/bc.rst @@ -57,7 +57,7 @@ Operation Normal API Type hint against Safe Safe Use method Safe Safe **When Implementing** -Implement method Not Safe Safe +Implement method Not Safe [1]_ Safe Add custom method Not Safe Not Safe Add custom method parameter Not Safe Not Safe Add parameter default value Safe Safe @@ -75,20 +75,20 @@ Type of Change Normal API ============================================== ============== ============== Remove entirely No No Change name or namespace No No -Add parent interface Yes [1]_ No +Add parent interface Yes [2]_ No Remove parent interface No No **Methods** -Add method Yes [1]_ No +Add method Yes [2]_ 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 Yes [2]_ Yes [2]_ -Add default value to a parameter Yes [1]_ No +Add parameter with a default value Yes [2]_ No +Remove parameter Yes [3]_ Yes [3]_ +Add default value to a parameter Yes [2]_ 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]_ [3]_ No +Remove type hint of a parameter Yes [2]_ No +Change return type Yes [2]_ [4]_ No ============================================== ============== ============== @@ -148,12 +148,12 @@ Extend Safe Safe Use public property Safe Safe Use public method Safe Safe **When Extending** -Use protected property Not Safe Safe -Use protected method Not Safe Safe +Use protected property Not Safe [1]_ Safe +Use protected method Not Safe [1]_ Safe Override public property Safe Safe -Override protected property Not Safe Safe -Override public method Not Safe Safe -Override protected method Not Safe Safe +Override protected property Not Safe [1]_ Safe +Override public method Not Safe [1]_ Safe +Override protected method Not Safe [1]_ Safe Add custom method Not Safe Not Safe Add custom method parameter Not Safe Not Safe Add parameter default value Safe Safe @@ -170,10 +170,10 @@ code of Symfony's classes Type of Change Normal API ================================================== ============== ============== Remove entirely No No -Make final Yes [1]_ No +Make final Yes [2]_ No Make abstract No No Change name or namespace No No -Change parent class Yes [4]_ Yes [4]_ +Change parent class Yes [5]_ Yes [5]_ Add interface Yes Yes Remove interface No No **Public Properties** @@ -182,48 +182,51 @@ 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 +Remove protected property Yes [2]_ No +Reduce visibility Yes [2]_ No **Constructors** -Add constructor without mandatory parameters Yes [1]_ Yes [1]_ -Remove constructor Yes [1]_ No +Add constructor without mandatory parameters Yes [2]_ Yes [2]_ +Remove constructor Yes [2]_ No Reduce visibility of a public constructor No No -Reduce visibility of a protected constructor Yes [1]_ No +Reduce visibility of a protected constructor Yes [2]_ 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 [1]_ No -Remove parameter Yes [2]_ Yes [2]_ -Add default value to a parameter Yes [1]_ No +Add parameter with a default value Yes [2]_ No +Remove parameter Yes [3]_ Yes [3]_ +Add default value to a parameter Yes [2]_ No Remove default value of a parameter No No -Add type hint to a parameter Yes [5]_ No -Remove type hint of a parameter Yes [1]_ No -Change return type Yes [1]_ [3]_ No +Add type hint to a parameter Yes [6]_ No +Remove type hint of a parameter Yes [2]_ No +Change return type Yes [2]_ [4]_ No **Protected Methods** Add protected method Yes Yes -Remove protected method Yes [1]_ No +Remove protected method Yes [2]_ 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 [1]_ No -Remove parameter Yes [2]_ Yes [2]_ -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]_ [3]_ No +Reduce visibility Yes [2]_ No +Add parameter without a default value Yes [2]_ No +Add parameter with a default value Yes [2]_ No +Remove parameter Yes [3]_ Yes [3]_ +Add default value to a parameter Yes [2]_ No +Remove default value of a parameter Yes [2]_ No +Add type hint to a parameter Yes [2]_ No +Remove type hint of a parameter Yes [2]_ No +Change return type Yes [2]_ [4]_ No ================================================== ============== ============== -.. [1] Should be avoided. When done, this change must be documented in the +.. [1] Your code may be broken by changes in the Symfony code. Such changes will + however be documented in the UPGRADE file. + +.. [2] Should be avoided. When done, this change must be documented in the UGPRADE file. -.. [2] Only the last parameter(s) of a method may be removed. +.. [3] Only the last parameter(s) of a method may be removed. -.. [3] The return type may only be changed to compatible types. The following +.. [4] The return type may only be changed to compatible types. The following type changes are allowed: =================== ================================================================== @@ -239,10 +242,10 @@ Change return type Yes [1]_ [3]_ No ``Countable`` array =================== ================================================================== -.. [4] When changing the parent class, the original parent class must remain an +.. [5] When changing the parent class, the original parent class must remain an ancestor of the class. -.. [5] A type hint may only be added if passing a value with a different type +.. [6] A type hint may only be added if passing a value with a different type previously generated a fatal error. .. _scalar type: http://php.net/manual/en/function.is-scalar.php From 4c5a55d6330d8c4a6ed781e8861d92a97bbb2dad Mon Sep 17 00:00:00 2001 From: Bernhard Schussek Date: Wed, 8 Jan 2014 11:24:04 +0100 Subject: [PATCH 12/39] Rearranged page to have different sections for different user bases --- contributing/code/bc.rst | 102 +++++++++++++++++++++------------------ 1 file changed, 55 insertions(+), 47 deletions(-) diff --git a/contributing/code/bc.rst b/contributing/code/bc.rst index 5949c27408f..d971916b94c 100644 --- a/contributing/code/bc.rst +++ b/contributing/code/bc.rst @@ -15,11 +15,17 @@ the rules listed below. parts of it if we discover problems or limitations. -Interfaces ----------- +Using Symfony Code +------------------ -Normal Interfaces -~~~~~~~~~~~~~~~~~ +You are using Symfony in your projects? Stick to the guidelines in this section +in order to guarantee smooth upgrades to all future 2.x versions. + + +Using Our Interfaces +~~~~~~~~~~~~~~~~~~~~ + +### Normal Interfaces All interfaces in the ``Symfony`` namespace are **safe for use**. That means that: @@ -37,8 +43,7 @@ Methods tagged with ``@api`` are treated as if they belonged to an API interface. -API Interfaces -~~~~~~~~~~~~~~ +### API Interfaces All interfaces tagged with ``@api`` are also **safe for implementation**. That means that: @@ -46,8 +51,7 @@ means that: * You can safely implement the interface. -Safe Operations -~~~~~~~~~~~~~~~ +### Safe Operations The following table summarizes the safe operations when using our interfaces: @@ -64,39 +68,10 @@ Add parameter default value Safe Safe ============================================== ============== ============== -Allowed Changes -~~~~~~~~~~~~~~~ - -This table tells you which changes you are allowed to do when working on the -code of Symfony's interfaces: - -============================================== ============== ============== -Type of Change Normal API -============================================== ============== ============== -Remove entirely No No -Change name or namespace No No -Add parent interface Yes [2]_ No -Remove parent interface No No -**Methods** -Add method Yes [2]_ No -Remove method No No -Change name No No -Add parameter without a default value No No -Add parameter with a default value Yes [2]_ No -Remove parameter Yes [3]_ Yes [3]_ -Add default value to a parameter Yes [2]_ No -Remove default value of a parameter No No -Add type hint to a parameter No No -Remove type hint of a parameter Yes [2]_ No -Change return type Yes [2]_ [4]_ No -============================================== ============== ============== - - -Classes -------- +Using Our Classes +~~~~~~~~~~~~~~~~~ -Normal Classes -~~~~~~~~~~~~~~ +### Normal Classes All classes in the ``Symfony`` namespace are **safe for use**. That means that: @@ -121,8 +96,7 @@ Properties and methods tagged with ``@api`` are treated as if they belonged to an API class. -API Classes -~~~~~~~~~~~ +### API Classes All classes tagged with ``@api`` are also **safe for extension**. That means that: @@ -134,8 +108,7 @@ that: * You can safely override public or protected methods. -Safe Operations -~~~~~~~~~~~~~~~ +### Safe Operations The following table summarizes the safe operations when using our classes: @@ -160,11 +133,46 @@ Add parameter default value Safe Safe ============================================== ============== ============== -Allowed Changes -~~~~~~~~~~~~~~~ +Working on Symfony Code +----------------------- + +Do you want to help us improve Symfony? That's great! However, please stick +to the rules listed below in order to ensure smooth upgrades for our users. + + +Changing Our Interfaces +~~~~~~~~~~~~~~~~~~~~~~~ + +This table tells you which changes you are allowed to do when working on +Symfony's interfaces: + +============================================== ============== ============== +Type of Change Normal API +============================================== ============== ============== +Remove entirely No No +Change name or namespace No No +Add parent interface Yes [2]_ No +Remove parent interface No No +**Methods** +Add method Yes [2]_ No +Remove method No No +Change name No No +Add parameter without a default value No No +Add parameter with a default value Yes [2]_ No +Remove parameter Yes [3]_ Yes [3]_ +Add default value to a parameter Yes [2]_ No +Remove default value of a parameter No No +Add type hint to a parameter No No +Remove type hint of a parameter Yes [2]_ No +Change return type Yes [2]_ [4]_ No +============================================== ============== ============== + + +Changing Our Classes +~~~~~~~~~~~~~~~~~~~~ This table tells you which changes you are allowed to do when working on the -code of Symfony's classes +Symfony's classes ================================================== ============== ============== Type of Change Normal API From c6e850d630d9b6a7ab45b5045b3b16c7f056251e Mon Sep 17 00:00:00 2001 From: Bernhard Schussek Date: Wed, 8 Jan 2014 11:26:06 +0100 Subject: [PATCH 13/39] Language fixes --- contributing/code/bc.rst | 11 ++++++----- 1 file changed, 6 insertions(+), 5 deletions(-) diff --git a/contributing/code/bc.rst b/contributing/code/bc.rst index d971916b94c..fcfa1e57a0e 100644 --- a/contributing/code/bc.rst +++ b/contributing/code/bc.rst @@ -3,11 +3,12 @@ Our Backwards Compatibility Promise As of Symfony 2.3, 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. +However, backwards compatibility comes in many different flavors. -If you are contributing to Symfony, make sure that your code changes comply to -the rules listed below. +This page has two different target audiences: If you are using Symfony, it will +tell you how to make sure that you will be able to upgrade smoothly to all +future 2.x versions. If you are contributing, this page will tell you the rules +you need to follow to ensure smooth upgrades for our users. .. note:: @@ -230,7 +231,7 @@ Change return type Yes [2]_ [4]_ No however be documented in the UPGRADE file. .. [2] Should be avoided. When done, this change must be documented in the - UGPRADE file. + UPGRADE file. .. [3] Only the last parameter(s) of a method may be removed. From db762889deb465f9838ec132db92c1cd22cdb6bd Mon Sep 17 00:00:00 2001 From: Bernhard Schussek Date: Wed, 8 Jan 2014 11:28:52 +0100 Subject: [PATCH 14/39] Fixed headings --- contributing/code/bc.rst | 18 ++++++++++++------ 1 file changed, 12 insertions(+), 6 deletions(-) diff --git a/contributing/code/bc.rst b/contributing/code/bc.rst index fcfa1e57a0e..29e1bbcba0a 100644 --- a/contributing/code/bc.rst +++ b/contributing/code/bc.rst @@ -26,7 +26,8 @@ in order to guarantee smooth upgrades to all future 2.x versions. Using Our Interfaces ~~~~~~~~~~~~~~~~~~~~ -### Normal Interfaces +Normal Interfaces +................. All interfaces in the ``Symfony`` namespace are **safe for use**. That means that: @@ -44,7 +45,8 @@ Methods tagged with ``@api`` are treated as if they belonged to an API interface. -### API Interfaces +API Interfaces +.............. All interfaces tagged with ``@api`` are also **safe for implementation**. That means that: @@ -52,7 +54,8 @@ means that: * You can safely implement the interface. -### Safe Operations +Safe Operations +............... The following table summarizes the safe operations when using our interfaces: @@ -72,7 +75,8 @@ Add parameter default value Safe Safe Using Our Classes ~~~~~~~~~~~~~~~~~ -### Normal Classes +Normal Classes +.............. All classes in the ``Symfony`` namespace are **safe for use**. That means that: @@ -97,7 +101,8 @@ Properties and methods tagged with ``@api`` are treated as if they belonged to an API class. -### API Classes +API Classes +........... All classes tagged with ``@api`` are also **safe for extension**. That means that: @@ -109,7 +114,8 @@ that: * You can safely override public or protected methods. -### Safe Operations +Safe Operations +............... The following table summarizes the safe operations when using our classes: From 54fd83623d7424ce5547624c14662580ab407619 Mon Sep 17 00:00:00 2001 From: Bernhard Schussek Date: Wed, 8 Jan 2014 11:29:39 +0100 Subject: [PATCH 15/39] Language improvements --- contributing/code/bc.rst | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/contributing/code/bc.rst b/contributing/code/bc.rst index 29e1bbcba0a..603ef402e39 100644 --- a/contributing/code/bc.rst +++ b/contributing/code/bc.rst @@ -147,8 +147,8 @@ Do you want to help us improve Symfony? That's great! However, please stick to the rules listed below in order to ensure smooth upgrades for our users. -Changing Our Interfaces -~~~~~~~~~~~~~~~~~~~~~~~ +Changing Interfaces +~~~~~~~~~~~~~~~~~~~ This table tells you which changes you are allowed to do when working on Symfony's interfaces: @@ -175,11 +175,11 @@ Change return type Yes [2]_ [4]_ No ============================================== ============== ============== -Changing Our Classes -~~~~~~~~~~~~~~~~~~~~ +Changing Classes +~~~~~~~~~~~~~~~~ -This table tells you which changes you are allowed to do when working on the -Symfony's classes +This table tells you which changes you are allowed to do when working on +Symfony's classes: ================================================== ============== ============== Type of Change Normal API From 00c6ebedc581d44c1df2c2317d03f3e4b15c75ce Mon Sep 17 00:00:00 2001 From: Bernhard Schussek Date: Wed, 8 Jan 2014 11:47:13 +0100 Subject: [PATCH 16/39] Fixed safety statements --- contributing/code/bc.rst | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/contributing/code/bc.rst b/contributing/code/bc.rst index 603ef402e39..4c19fe8a963 100644 --- a/contributing/code/bc.rst +++ b/contributing/code/bc.rst @@ -66,8 +66,8 @@ Type hint against Safe Safe Use method Safe Safe **When Implementing** Implement method Not Safe [1]_ Safe -Add custom method Not Safe Not Safe -Add custom method parameter Not Safe Not Safe +Add custom method Not Safe [1]_ Safe +Add custom method parameter Not Safe [1]_ Safe Add parameter default value Safe Safe ============================================== ============== ============== @@ -135,7 +135,7 @@ Override protected property Not Safe [1]_ Safe Override public method Not Safe [1]_ Safe Override protected method Not Safe [1]_ Safe Add custom method Not Safe Not Safe -Add custom method parameter Not Safe Not Safe +Add custom method parameter Not Safe [1]_ Safe Add parameter default value Safe Safe ============================================== ============== ============== From efd39119851463502e348b3b19a980bef41c2a22 Mon Sep 17 00:00:00 2001 From: Bernhard Schussek Date: Wed, 8 Jan 2014 11:50:22 +0100 Subject: [PATCH 17/39] Added that adding custom properties is not safe --- contributing/code/bc.rst | 1 + 1 file changed, 1 insertion(+) diff --git a/contributing/code/bc.rst b/contributing/code/bc.rst index 4c19fe8a963..27d0eee21d5 100644 --- a/contributing/code/bc.rst +++ b/contributing/code/bc.rst @@ -134,6 +134,7 @@ Override public property Safe Safe Override protected property Not Safe [1]_ Safe Override public method Not Safe [1]_ Safe Override protected method Not Safe [1]_ Safe +Add custom property Not Safe Not Safe Add custom method Not Safe Not Safe Add custom method parameter Not Safe [1]_ Safe Add parameter default value Safe Safe From dcbe79a131348f1596e2cc6491f5f07e3f5beaf4 Mon Sep 17 00:00:00 2001 From: Bernhard Schussek Date: Thu, 9 Jan 2014 17:00:19 +0100 Subject: [PATCH 18/39] Improved wording --- contributing/code/bc.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/contributing/code/bc.rst b/contributing/code/bc.rst index 27d0eee21d5..02061e32799 100644 --- a/contributing/code/bc.rst +++ b/contributing/code/bc.rst @@ -64,7 +64,7 @@ Operation Normal API ============================================== ============== ============== Type hint against Safe Safe Use method Safe Safe -**When Implementing** +**In Implementing Classes** Implement method Not Safe [1]_ Safe Add custom method Not Safe [1]_ Safe Add custom method parameter Not Safe [1]_ Safe @@ -127,7 +127,7 @@ Create instance Safe Safe Extend Safe Safe Use public property Safe Safe Use public method Safe Safe -**When Extending** +**In Extending Classes** Use protected property Not Safe [1]_ Safe Use protected method Not Safe [1]_ Safe Override public property Safe Safe From af3a645a32d9d5ebf6cf76a2c1dffa78240cf68d Mon Sep 17 00:00:00 2001 From: Bernhard Schussek Date: Thu, 9 Jan 2014 17:04:27 +0100 Subject: [PATCH 19/39] Added note about requesting `@api` tags --- contributing/code/bc.rst | 10 ++++++++++ 1 file changed, 10 insertions(+) diff --git a/contributing/code/bc.rst b/contributing/code/bc.rst index 02061e32799..e225f6dcfcd 100644 --- a/contributing/code/bc.rst +++ b/contributing/code/bc.rst @@ -71,6 +71,10 @@ Add custom method parameter Not Safe [1]_ Safe Add parameter default value Safe Safe ============================================== ============== ============== +If you need to do any of the things marked as "Not Safe" above, feel free to +ask us whether the ``@api`` tag can be added on the respective Symfony code. +For that, simply open a `new ticket on GitHub`_. + Using Our Classes ~~~~~~~~~~~~~~~~~ @@ -140,6 +144,10 @@ Add custom method parameter Not Safe [1]_ Safe Add parameter default value Safe Safe ============================================== ============== ============== +If you need to do any of the things marked as "Not Safe" above, feel free to +ask us whether the ``@api`` tag can be added on the respective Symfony code. +For that, simply open a `new ticket on GitHub`_. + Working on Symfony Code ----------------------- @@ -273,3 +281,5 @@ Change return type Yes [2]_ [4]_ No .. _integer values: http://www.php.net/manual/en/function.intval.php .. _float values: http://www.php.net/manual/en/function.floatval.php + +.. _new ticket on GitHub: https://github.com/symfony/symfony/issues/new From be766446be3db241d3a7a5c9417a55af4e2d0387 Mon Sep 17 00:00:00 2001 From: Bernhard Schussek Date: Thu, 9 Jan 2014 17:19:03 +0100 Subject: [PATCH 20/39] Added information about internal classes and interfaces --- contributing/code/bc.rst | 14 ++++++++++++++ 1 file changed, 14 insertions(+) diff --git a/contributing/code/bc.rst b/contributing/code/bc.rst index e225f6dcfcd..102fba37402 100644 --- a/contributing/code/bc.rst +++ b/contributing/code/bc.rst @@ -54,6 +54,13 @@ means that: * You can safely implement the interface. +Internal Interfaces +................... + +Interfaces or interface methods tagged with ``@internal`` are meant for internal +use in Symfony only and should never be used nor implemented. + + Safe Operations ............... @@ -118,6 +125,13 @@ that: * You can safely override public or protected methods. +Internal Classes +................ + +Classes, properties and class methods tagged with ``@internal`` are meant for +internal use in Symfony only and should never be used nor extended. + + Safe Operations ............... From dfb3e8b343d864d3d69f2986079889f1bbdb3000 Mon Sep 17 00:00:00 2001 From: Bernhard Schussek Date: Thu, 9 Jan 2014 17:25:28 +0100 Subject: [PATCH 21/39] Improved wording --- contributing/code/bc.rst | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/contributing/code/bc.rst b/contributing/code/bc.rst index 102fba37402..e7c05bdafd5 100644 --- a/contributing/code/bc.rst +++ b/contributing/code/bc.rst @@ -7,8 +7,8 @@ However, backwards compatibility comes in many different flavors. This page has two different target audiences: If you are using Symfony, it will tell you how to make sure that you will be able to upgrade smoothly to all -future 2.x versions. If you are contributing, this page will tell you the rules -you need to follow to ensure smooth upgrades for our users. +future 2.x versions. If you are contributing to Symfony, this page will tell you +the rules that you need to follow to ensure smooth upgrades for our users. .. note:: @@ -19,8 +19,8 @@ you need to follow to ensure smooth upgrades for our users. Using Symfony Code ------------------ -You are using Symfony in your projects? Stick to the guidelines in this section -in order to guarantee smooth upgrades to all future 2.x versions. +You are using Symfony in your projects? Then stick to the guidelines in this +section in order to guarantee smooth upgrades to all future 2.x versions. Using Our Interfaces @@ -58,7 +58,7 @@ Internal Interfaces ................... Interfaces or interface methods tagged with ``@internal`` are meant for internal -use in Symfony only and should never be used nor implemented. +use in Symfony only. You should never use nor implement them. Safe Operations @@ -129,7 +129,7 @@ Internal Classes ................ Classes, properties and class methods tagged with ``@internal`` are meant for -internal use in Symfony only and should never be used nor extended. +internal use in Symfony only. You should never use nor extend them. Safe Operations From 6501a35f723206972561669951a186d6841f4943 Mon Sep 17 00:00:00 2001 From: Bernhard Schussek Date: Thu, 9 Jan 2014 17:34:24 +0100 Subject: [PATCH 22/39] Added information about changing return types that are classes or interfaces --- contributing/code/bc.rst | 2 ++ 1 file changed, 2 insertions(+) diff --git a/contributing/code/bc.rst b/contributing/code/bc.rst index e7c05bdafd5..3bd836618ae 100644 --- a/contributing/code/bc.rst +++ b/contributing/code/bc.rst @@ -278,6 +278,8 @@ Change return type Yes [2]_ [4]_ No ``ArrayAccess`` array ``Traversable`` array ``Countable`` array + class ```` any subclass of ```` + interface ```` any subinterface or implementing class of ```` =================== ================================================================== .. [5] When changing the parent class, the original parent class must remain an From 0c6420fbaae571f4a2723f6cd82c68229eed05c5 Mon Sep 17 00:00:00 2001 From: Bernhard Schussek Date: Thu, 9 Jan 2014 17:44:24 +0100 Subject: [PATCH 23/39] Added information about changing parameter types --- contributing/code/bc.rst | 35 ++++++++++++++++++++++++++--------- 1 file changed, 26 insertions(+), 9 deletions(-) diff --git a/contributing/code/bc.rst b/contributing/code/bc.rst index 3bd836618ae..6769a01424f 100644 --- a/contributing/code/bc.rst +++ b/contributing/code/bc.rst @@ -194,7 +194,8 @@ Add default value to a parameter Yes [2]_ No Remove default value of a parameter No No Add type hint to a parameter No No Remove type hint of a parameter Yes [2]_ No -Change return type Yes [2]_ [4]_ No +Change parameter type Yes [2]_ [4]_ No +Change return type Yes [2]_ [5]_ No ============================================== ============== ============== @@ -211,7 +212,7 @@ Remove entirely No No Make final Yes [2]_ No Make abstract No No Change name or namespace No No -Change parent class Yes [5]_ Yes [5]_ +Change parent class Yes [6]_ Yes [6]_ Add interface Yes Yes Remove interface No No **Public Properties** @@ -237,9 +238,10 @@ Add parameter with a default value Yes [2]_ No Remove parameter Yes [3]_ Yes [3]_ Add default value to a parameter Yes [2]_ No Remove default value of a parameter No No -Add type hint to a parameter Yes [6]_ No +Add type hint to a parameter Yes [7]_ No Remove type hint of a parameter Yes [2]_ No -Change return type Yes [2]_ [4]_ No +Change parameter type Yes [2]_ [4]_ No +Change return type Yes [2]_ [5]_ No **Protected Methods** Add protected method Yes Yes Remove protected method Yes [2]_ No @@ -252,7 +254,8 @@ Add default value to a parameter Yes [2]_ No Remove default value of a parameter Yes [2]_ No Add type hint to a parameter Yes [2]_ No Remove type hint of a parameter Yes [2]_ No -Change return type Yes [2]_ [4]_ No +Change parameter type Yes [2]_ [4]_ No +Change return type Yes [2]_ [5]_ No ================================================== ============== ============== @@ -264,8 +267,22 @@ Change return type Yes [2]_ [4]_ No .. [3] Only the last parameter(s) of a method may be removed. -.. [4] The return type may only be changed to compatible types. The following - type changes are allowed: +.. [4] The parameter type may only be changed to a compatible or less specific + type. The following type changes are allowed: + + =================== ================================================================== + Original Type New Type + =================== ================================================================== + boolean any `scalar type`_ with equivalent `boolean values`_ + string any `scalar type`_ or object with equivalent `string values`_ + integer any `scalar type`_ with equivalent `integer values`_ + float any `scalar type`_ with equivalent `float values`_ + class ```` any superclass or interface of ```` + interface ```` any superinterface of ```` + =================== ================================================================== + +.. [5] The return type may only be changed to a compatible or more specific + type. The following type changes are allowed: =================== ================================================================== Original Type New Type @@ -282,10 +299,10 @@ Change return type Yes [2]_ [4]_ No interface ```` any subinterface or implementing class of ```` =================== ================================================================== -.. [5] When changing the parent class, the original parent class must remain an +.. [6] When changing the parent class, the original parent class must remain an ancestor of the class. -.. [6] A type hint may only be added if passing a value with a different type +.. [7] A type hint may only be added if passing a value with a different type previously generated a fatal error. .. _scalar type: http://php.net/manual/en/function.is-scalar.php From 69768ddd2ac3807df3a87947c27cf8c7833a7b1a Mon Sep 17 00:00:00 2001 From: Bernhard Schussek Date: Fri, 10 Jan 2014 10:45:27 +0100 Subject: [PATCH 24/39] Improved wording: use -> call, access --- contributing/code/bc.rst | 22 +++++++++++++--------- 1 file changed, 13 insertions(+), 9 deletions(-) diff --git a/contributing/code/bc.rst b/contributing/code/bc.rst index 6769a01424f..58017243e0c 100644 --- a/contributing/code/bc.rst +++ b/contributing/code/bc.rst @@ -34,7 +34,7 @@ that: * You can safely type hint against the interface. -* You can safely use any of the methods provided by the interface. +* You can safely call any of the methods provided by the interface. However: @@ -70,7 +70,7 @@ The following table summarizes the safe operations when using our interfaces: Operation Normal API ============================================== ============== ============== Type hint against Safe Safe -Use method Safe Safe +Call method Safe Safe **In Implementing Classes** Implement method Not Safe [1]_ Safe Add custom method Not Safe [1]_ Safe @@ -97,7 +97,9 @@ All classes in the ``Symfony`` namespace are **safe for use**. That means that: * You can safely extend the class. -* You can safely use public properties and methods. +* You can safely access public properties. + +* You can safely call public methods. When extending the class: @@ -118,11 +120,13 @@ 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 access protected properties and methods. + +* You can safely call protected methods. * You can safely override protected properties. -* You can safely override public or protected methods. +* You can safely override public and protected methods. Internal Classes @@ -143,11 +147,11 @@ Operation Normal API Type hint against Safe Safe Create instance Safe Safe Extend Safe Safe -Use public property Safe Safe -Use public method Safe Safe +Access public property Safe Safe +Call public method Safe Safe **In Extending Classes** -Use protected property Not Safe [1]_ Safe -Use protected method Not Safe [1]_ Safe +Access protected property Not Safe [1]_ Safe +Call protected method Not Safe [1]_ Safe Override public property Safe Safe Override protected property Not Safe [1]_ Safe Override public method Not Safe [1]_ Safe From 5a160c51f73b75ecf15c1704ddc1b59973949f8b Mon Sep 17 00:00:00 2001 From: Bernhard Schussek Date: Fri, 10 Jan 2014 10:48:35 +0100 Subject: [PATCH 25/39] Added note about deprecated interfaces/classes --- contributing/code/bc.rst | 14 ++++++++++++++ 1 file changed, 14 insertions(+) diff --git a/contributing/code/bc.rst b/contributing/code/bc.rst index 58017243e0c..596967a719f 100644 --- a/contributing/code/bc.rst +++ b/contributing/code/bc.rst @@ -61,6 +61,13 @@ Interfaces or interface methods tagged with ``@internal`` are meant for internal use in Symfony only. You should never use nor implement them. +Deprecated Interfaces +..................... + +Interfaces or interface methods tagged with ``@deprecated`` will be removed in +a future Symfony version. You should never use nor implement them. + + Safe Operations ............... @@ -136,6 +143,13 @@ Classes, properties and class methods tagged with ``@internal`` are meant for internal use in Symfony only. You should never use nor extend them. +Deprecated Classes +.................. + +Classes, properties and class methods tagged with ``@deprecated`` will be +removed in a future Symfony version. You should never use nor extend them. + + Safe Operations ............... From ef1f021be35fb487f4e9f4770d3526a067f9bc80 Mon Sep 17 00:00:00 2001 From: Bernhard Schussek Date: Fri, 10 Jan 2014 10:58:36 +0100 Subject: [PATCH 26/39] Added note about test classes --- contributing/code/bc.rst | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/contributing/code/bc.rst b/contributing/code/bc.rst index 596967a719f..677109cb674 100644 --- a/contributing/code/bc.rst +++ b/contributing/code/bc.rst @@ -150,6 +150,13 @@ Classes, properties and class methods tagged with ``@deprecated`` will be removed in a future Symfony version. You should never use nor extend them. +Test Classes +............ + +All classes located in the various ``*\\Tests\\`` namespaces are meant for +internal use only. You should never create, extend or call them directly. + + Safe Operations ............... From 6d9edf14705864424ec5c409cfe201602857f784 Mon Sep 17 00:00:00 2001 From: Bernhard Schussek Date: Thu, 23 Jan 2014 09:11:26 +0100 Subject: [PATCH 27/39] Improved wording: Changed "safe" to "guaranteed" --- contributing/code/bc.rst | 116 +++++++++++++++++++-------------------- 1 file changed, 58 insertions(+), 58 deletions(-) diff --git a/contributing/code/bc.rst b/contributing/code/bc.rst index 677109cb674..621449e6130 100644 --- a/contributing/code/bc.rst +++ b/contributing/code/bc.rst @@ -32,17 +32,14 @@ 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 type hint against the interface. -* You can safely call any of the methods provided by the interface. +* You can call any of the methods provided by the interface. However: -* You cannot safely implement the interface. The interface may change, but all - changes will be documented in the UPGRADE file. - -Methods tagged with ``@api`` are treated as if they belonged to an API -interface. +* You cannot implement the interface. The interface may change, but all changes + will be documented in the UPGRADE file. API Interfaces @@ -51,7 +48,7 @@ API Interfaces All interfaces tagged with ``@api`` are also **safe for implementation**. That means that: -* You can safely implement the interface. +* You can implement the interface. Internal Interfaces @@ -68,24 +65,25 @@ Interfaces or interface methods tagged with ``@deprecated`` will be removed in a future Symfony version. You should never use nor implement them. -Safe Operations -............... +Guarantee Details +................. -The following table summarizes the safe operations when using our interfaces: +When using our interfaces, we guarantee full backwards compatibility for the +following use cases: ============================================== ============== ============== -Operation Normal API +Use Case Normal API ============================================== ============== ============== -Type hint against Safe Safe -Call method Safe Safe +Type hint against Yes Yes +Call method Yes Yes **In Implementing Classes** -Implement method Not Safe [1]_ Safe -Add custom method Not Safe [1]_ Safe -Add custom method parameter Not Safe [1]_ Safe -Add parameter default value Safe Safe +Implement method No [1]_ Yes +Add custom method No [1]_ Yes +Add custom method parameter No [1]_ Yes +Add parameter default value Yes Yes ============================================== ============== ============== -If you need to do any of the things marked as "Not Safe" above, feel free to +If you need to do any of the things marked with "No" above, feel free to ask us whether the ``@api`` tag can be added on the respective Symfony code. For that, simply open a `new ticket on GitHub`_. @@ -98,27 +96,24 @@ Normal Classes All classes in the ``Symfony`` namespace are **safe for use**. That means that: -* You can safely type hint against the class' name. +* You can type hint against the class' name. -* You can safely create new instances. +* You can create new instances. -* You can safely extend the class. +* You can extend the class. -* You can safely access public properties. +* You can access public properties. -* You can safely call public methods. +* You can call public methods. When extending the class: -* You can safely override public properties. +* You can override public properties. However: -* You cannot safely override methods in extending classes. The class may change, - but all changes will be documented in the UPGRADE file. - -Properties and methods tagged with ``@api`` are treated as if they belonged -to an API class. +* You cannot override methods in extending classes. The class may change, but + all changes will be documented in the UPGRADE file. API Classes @@ -127,27 +122,31 @@ API Classes All classes tagged with ``@api`` are also **safe for extension**. That means that: -* You can safely access protected properties and methods. +* You can access protected properties and methods. -* You can safely call protected methods. +* You can call protected methods. -* You can safely override protected properties. +* You can override protected properties. -* You can safely override public and protected methods. +* You can override public and protected methods. + +Properties and methods tagged with ``@api`` are treated as if they belonged +to an API class. That means that you can call or override them regardless of +whether their class has the ``@api`` tag or not. Internal Classes ................ -Classes, properties and class methods tagged with ``@internal`` are meant for -internal use in Symfony only. You should never use nor extend them. +Classes, properties and methods tagged with ``@internal`` are meant for internal +use in Symfony only. You should never use nor extend them. Deprecated Classes .................. -Classes, properties and class methods tagged with ``@deprecated`` will be -removed in a future Symfony version. You should never use nor extend them. +Classes, properties and methods tagged with ``@deprecated`` will be removed in +a future Symfony version. You should never use nor extend them. Test Classes @@ -157,33 +156,34 @@ All classes located in the various ``*\\Tests\\`` namespaces are meant for internal use only. You should never create, extend or call them directly. -Safe Operations -............... +Guarantee Details +................. -The following table summarizes the safe operations when using our classes: +When using our classes, we guarantee full backwards compatibility for the +following use cases: ============================================== ============== ============== -Operation Normal API +Use Case Normal API ============================================== ============== ============== -Type hint against Safe Safe -Create instance Safe Safe -Extend Safe Safe -Access public property Safe Safe -Call public method Safe Safe +Type hint against Yes Yes +Create instance Yes Yes +Extend Yes Yes +Access public property Yes Yes +Call public method Yes Yes **In Extending Classes** -Access protected property Not Safe [1]_ Safe -Call protected method Not Safe [1]_ Safe -Override public property Safe Safe -Override protected property Not Safe [1]_ Safe -Override public method Not Safe [1]_ Safe -Override protected method Not Safe [1]_ Safe -Add custom property Not Safe Not Safe -Add custom method Not Safe Not Safe -Add custom method parameter Not Safe [1]_ Safe -Add parameter default value Safe Safe +Access protected property No [1]_ Yes +Call protected method No [1]_ Yes +Override public property Yes Yes +Override protected property No [1]_ Yes +Override public method No [1]_ Yes +Override protected method No [1]_ Yes +Add custom property No No +Add custom method No No +Add custom method parameter No [1]_ Yes +Add parameter default value Yes Yes ============================================== ============== ============== -If you need to do any of the things marked as "Not Safe" above, feel free to +If you need to do any of the things marked with "No" above, feel free to ask us whether the ``@api`` tag can be added on the respective Symfony code. For that, simply open a `new ticket on GitHub`_. From 8c6c7bf5b31a4cadde04fbf9892fe34ad7495285 Mon Sep 17 00:00:00 2001 From: Bernhard Schussek Date: Thu, 23 Jan 2014 09:33:05 +0100 Subject: [PATCH 28/39] Simplified usage description --- contributing/code/bc.rst | 172 ++++++++++++--------------------------- 1 file changed, 52 insertions(+), 120 deletions(-) diff --git a/contributing/code/bc.rst b/contributing/code/bc.rst index 621449e6130..395cbb58294 100644 --- a/contributing/code/bc.rst +++ b/contributing/code/bc.rst @@ -1,8 +1,8 @@ Our Backwards Compatibility Promise =================================== -As of Symfony 2.3, we promise you backwards compatibility for all further 2.x -releases. Ensuring smooth upgrades of your projects is our first priority. +As of Symfony 2.3, we promise you backwards compatibility (BC) 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 has two different target audiences: If you are using Symfony, it will @@ -26,53 +26,24 @@ section in order to guarantee smooth upgrades to all future 2.x versions. Using Our Interfaces ~~~~~~~~~~~~~~~~~~~~ -Normal Interfaces -................. +In Symfony, we distinguish between regular and API interfaces. API interfaces +are marked with an ``@api`` tag in their source code. For example:: -All interfaces in the ``Symfony`` namespace are **safe for use**. That means -that: + /** + * HttpKernelInterface handles a Request to convert it to a Response. + * + * @author Fabien Potencier + * + * @api + */ + interface HttpKernelInterface + { -* You can type hint against the interface. - -* You can call any of the methods provided by the interface. - -However: - -* You cannot implement the interface. The interface may change, but all changes - will be documented in the UPGRADE file. - - -API Interfaces -.............. - -All interfaces tagged with ``@api`` are also **safe for implementation**. That -means that: - -* You can implement the interface. - - -Internal Interfaces -................... - -Interfaces or interface methods tagged with ``@internal`` are meant for internal -use in Symfony only. You should never use nor implement them. - - -Deprecated Interfaces -..................... - -Interfaces or interface methods tagged with ``@deprecated`` will be removed in -a future Symfony version. You should never use nor implement them. - - -Guarantee Details -................. - -When using our interfaces, we guarantee full backwards compatibility for the +When using these interfaces, we guarantee full backwards compatibility for the following use cases: ============================================== ============== ============== -Use Case Normal API +Use Case Regular API ============================================== ============== ============== Type hint against Yes Yes Call method Yes Yes @@ -83,87 +54,37 @@ Add custom method parameter No [1]_ Yes Add parameter default value Yes Yes ============================================== ============== ============== -If you need to do any of the things marked with "No" above, feel free to -ask us whether the ``@api`` tag can be added on the respective Symfony code. -For that, simply open a `new ticket on GitHub`_. - - -Using Our Classes -~~~~~~~~~~~~~~~~~ - -Normal Classes -.............. - -All classes in the ``Symfony`` namespace are **safe for use**. That means that: - -* You can type hint against the class' name. - -* You can create new instances. - -* You can extend the class. - -* You can access public properties. - -* You can call public methods. - -When extending the class: - -* You can override public properties. - -However: - -* You cannot override methods in extending classes. The class may change, but - all changes will be documented in the UPGRADE file. - - -API Classes -........... - -All classes tagged with ``@api`` are also **safe for extension**. That means -that: - -* You can access protected properties and methods. - -* You can call protected methods. - -* You can override protected properties. - -* You can override public and protected methods. - -Properties and methods tagged with ``@api`` are treated as if they belonged -to an API class. That means that you can call or override them regardless of -whether their class has the ``@api`` tag or not. - - -Internal Classes -................ - -Classes, properties and methods tagged with ``@internal`` are meant for internal -use in Symfony only. You should never use nor extend them. - - -Deprecated Classes -.................. +.. note:: -Classes, properties and methods tagged with ``@deprecated`` will be removed in -a future Symfony version. You should never use nor extend them. + If you need to do any of the things marked with "No" above, feel free to + ask us whether the ``@api`` tag can be added on the respective Symfony code. + For that, simply open a `new ticket on GitHub`_. +Interfaces or interface methods tagged with ``@internal`` should never be +implemented or used. -Test Classes -............ -All classes located in the various ``*\\Tests\\`` namespaces are meant for -internal use only. You should never create, extend or call them directly. +Using Our Classes +~~~~~~~~~~~~~~~~~ +Just like with interfaces, we also distinguish between regular and API classes. +Like API interfaces, API classes are marked with an ``@api`` tag:: -Guarantee Details -................. + /** + * Request represents an HTTP request. + * + * @author Fabien Potencier + * + * @api + */ + class Request + { -When using our classes, we guarantee full backwards compatibility for the +When using these classes, we guarantee full backwards compatibility for the following use cases: ============================================== ============== ============== -Use Case Normal API +Use Case Regular API ============================================== ============== ============== Type hint against Yes Yes Create instance Yes Yes @@ -183,9 +104,20 @@ Add custom method parameter No [1]_ Yes Add parameter default value Yes Yes ============================================== ============== ============== -If you need to do any of the things marked with "No" above, feel free to -ask us whether the ``@api`` tag can be added on the respective Symfony code. -For that, simply open a `new ticket on GitHub`_. +.. note:: + + If you need to do any of the things marked with "No" above, feel free to + ask us whether the ``@api`` tag can be added on the respective Symfony code. + For that, simply open a `new ticket on GitHub`_. + +In some cases, only specific properties and methods are tagged with the ``@api`` +tag, even though their class is not. In these cases, we guarantee full backwards +compatibility for the tagged properties and methods (as indicated in the column +"API" above), but not for the rest of the class. + +Classes, properties and methods tagged with ``@internal`` should never be +created, extended or called directly. The same applies to all classes located in +the various ``*\\Tests\\`` namespaces. Working on Symfony Code @@ -202,7 +134,7 @@ This table tells you which changes you are allowed to do when working on Symfony's interfaces: ============================================== ============== ============== -Type of Change Normal API +Type of Change Regular API ============================================== ============== ============== Remove entirely No No Change name or namespace No No @@ -231,7 +163,7 @@ This table tells you which changes you are allowed to do when working on Symfony's classes: ================================================== ============== ============== -Type of Change Normal API +Type of Change Regular API ================================================== ============== ============== Remove entirely No No Make final Yes [2]_ No From 486845210076d70e6a1685c06a973226e8fe4040 Mon Sep 17 00:00:00 2001 From: Bernhard Schussek Date: Thu, 23 Jan 2014 09:55:28 +0100 Subject: [PATCH 29/39] Added prose about the difference between regular/API classes/interfaces --- contributing/code/bc.rst | 19 +++++++++++++++---- 1 file changed, 15 insertions(+), 4 deletions(-) diff --git a/contributing/code/bc.rst b/contributing/code/bc.rst index 395cbb58294..c5eff1f9a24 100644 --- a/contributing/code/bc.rst +++ b/contributing/code/bc.rst @@ -39,8 +39,14 @@ are marked with an ``@api`` tag in their source code. For example:: interface HttpKernelInterface { -When using these interfaces, we guarantee full backwards compatibility for the -following use cases: +In simple words, the difference between regular and API interfaces is that you +can implement API interfaces yourself and we will guarantee full backwards +compatibility. The same is not true for regular interfaces: We may, for example, +add an optional parameter or a new method to them and thus break your own +implementation. + +In detail, we guarantee full backwards compatibility for the following use +cases: ============================================== ============== ============== Use Case Regular API @@ -80,8 +86,13 @@ Like API interfaces, API classes are marked with an ``@api`` tag:: class Request { -When using these classes, we guarantee full backwards compatibility for the -following use cases: +The difference between regular and API classes is that we guarantee full +backwards compatibility if you extend an API class and override its methods, +but not for regular classes. In regular classes, we may for example add an +optional parameter to a method and thus break your overridden method. + +Again, here are the details about which use cases we guarantee full backwards +compatibility for: ============================================== ============== ============== Use Case Regular API From e11335fc3712f94600134d4964cab92881b65d3d Mon Sep 17 00:00:00 2001 From: Bernhard Schussek Date: Fri, 24 Jan 2014 15:41:05 +0100 Subject: [PATCH 30/39] Improved the wording of the "Using Symfony" section --- contributing/code/bc.rst | 192 ++++++++++++++++++++++----------------- 1 file changed, 111 insertions(+), 81 deletions(-) diff --git a/contributing/code/bc.rst b/contributing/code/bc.rst index c5eff1f9a24..237555777f5 100644 --- a/contributing/code/bc.rst +++ b/contributing/code/bc.rst @@ -1,33 +1,42 @@ Our Backwards Compatibility Promise =================================== -As of Symfony 2.3, we promise you backwards compatibility (BC) for all further -2.x releases. Ensuring smooth upgrades of your projects is our first priority. -However, backwards compatibility comes in many different flavors. +If you are using Symfony, we promise you backwards compatibility (BC) for all +major releases (2.x, 3.x, ...). Ensuring smooth upgrades of your projects is our +first priority. However, backwards compatibility comes in many different flavors. + +.. note:: + + This promise was introduced with Symfony 2.3 and does not apply to previous + versions of Symfony. This page has two different target audiences: If you are using Symfony, it will tell you how to make sure that you will be able to upgrade smoothly to all future 2.x versions. If you are contributing to Symfony, this page will tell you the rules that you need to follow to ensure smooth upgrades for our users. -.. note:: - - This promise is in trial until April 15th, 2014. Until then, we may change - parts of it if we discover problems or limitations. - - Using Symfony Code ------------------ -You are using Symfony in your projects? Then stick to the guidelines in this -section in order to guarantee smooth upgrades to all future 2.x versions. - +If you are using Symfony in your projects, the following guidelines will help +you to ensure smooth upgrades to all future minor releases of Symfony (such as +2.5, 2.6 and so on). Using Our Interfaces ~~~~~~~~~~~~~~~~~~~~ -In Symfony, we distinguish between regular and API interfaces. API interfaces -are marked with an ``@api`` tag in their source code. For example:: +All interfaces shipped with Symfony can be used in type hints. You can also call +any of the methods that they declare. We guarantee that we won't break code that +sticks to these rules. + +.. note:: + + The exception to this rule are interfaces tagged with ``@internal``. Such + interfaces should never be used or implemented. + +If you want to implement an interface, you should first make sure that the +interface is an API interface. You can recognize API interfaces by the ``@api`` +tag in their source code:: /** * HttpKernelInterface handles a Request to convert it to a Response. @@ -39,40 +48,51 @@ are marked with an ``@api`` tag in their source code. For example:: interface HttpKernelInterface { -In simple words, the difference between regular and API interfaces is that you -can implement API interfaces yourself and we will guarantee full backwards -compatibility. The same is not true for regular interfaces: We may, for example, -add an optional parameter or a new method to them and thus break your own -implementation. - -In detail, we guarantee full backwards compatibility for the following use -cases: - -============================================== ============== ============== -Use Case Regular API -============================================== ============== ============== -Type hint against Yes Yes -Call method Yes Yes -**In Implementing Classes** -Implement method No [1]_ Yes -Add custom method No [1]_ Yes -Add custom method parameter No [1]_ Yes -Add parameter default value Yes Yes -============================================== ============== ============== +If you implement an API interface, we promise that we won't ever break your +code. Regular interfaces, by contrast, should never be implemented, because if +we add a new method to the interface or add a new optional parameter to the +signature of a method, we would generate a fatal error in your application. + +The following table explains in detail which use cases are covered by our +backwards compatibility promise: + ++-----------------------------------------------+---------------+---------------+ +| Use Case | Regular | API | ++-----------------------------------------------+---------------+---------------+ +| If you... | Then we guarantee BC... | ++===============================================+===============+===============+ +| Type hint against the interface | Yes | Yes | ++-----------------------------------------------+---------------+---------------+ +| Call a method | Yes | Yes | ++-----------------------------------------------+---------------+---------------+ +| **If you implement the interface and...** | **Then we guarantee BC...** | ++-----------------------------------------------+---------------+---------------+ +| Implement a method | No [1]_ | Yes | ++-----------------------------------------------+---------------+---------------+ +| Add a parameter to an implemented method | No [1]_ | Yes | ++-----------------------------------------------+---------------+---------------+ +| Add a default value to a parameter | Yes | Yes | ++-----------------------------------------------+---------------+---------------+ .. note:: - If you need to do any of the things marked with "No" above, feel free to - ask us whether the ``@api`` tag can be added on the respective Symfony code. - For that, simply open a `new ticket on GitHub`_. - -Interfaces or interface methods tagged with ``@internal`` should never be -implemented or used. - + If you think that one of our regular interfaces should have an ``@api`` tag, + put your request into a `new ticket on GitHub`_. We will then evaluate + whether we can add the tag or not. Using Our Classes ~~~~~~~~~~~~~~~~~ +All classes provided by Symfony may be instantiated and accessed through their +public methods and properties. + +.. note:: + + Classes, properties and methods that bear the tag ``@internal`` as well as + the classes located in the various ``*\\Tests\\`` namespaces are an + exception to this rule. They are meant for internal use only and should not + be accessed by your own code. + Just like with interfaces, we also distinguish between regular and API classes. Like API interfaces, API classes are marked with an ``@api`` tag:: @@ -87,49 +107,62 @@ Like API interfaces, API classes are marked with an ``@api`` tag:: { The difference between regular and API classes is that we guarantee full -backwards compatibility if you extend an API class and override its methods, -but not for regular classes. In regular classes, we may for example add an -optional parameter to a method and thus break your overridden method. - -Again, here are the details about which use cases we guarantee full backwards -compatibility for: - -============================================== ============== ============== -Use Case Regular API -============================================== ============== ============== -Type hint against Yes Yes -Create instance Yes Yes -Extend Yes Yes -Access public property Yes Yes -Call public method Yes Yes -**In Extending Classes** -Access protected property No [1]_ Yes -Call protected method No [1]_ Yes -Override public property Yes Yes -Override protected property No [1]_ Yes -Override public method No [1]_ Yes -Override protected method No [1]_ Yes -Add custom property No No -Add custom method No No -Add custom method parameter No [1]_ Yes -Add parameter default value Yes Yes -============================================== ============== ============== - -.. note:: - - If you need to do any of the things marked with "No" above, feel free to - ask us whether the ``@api`` tag can be added on the respective Symfony code. - For that, simply open a `new ticket on GitHub`_. +backwards compatibility if you extend an API class and override its methods. We +can't give the same promise for regular classes, because there we may, for +example, add an optional parameter to a method. Consequently, the signature of +your overridden method won't match anymore and generate a fatal error. In some cases, only specific properties and methods are tagged with the ``@api`` tag, even though their class is not. In these cases, we guarantee full backwards compatibility for the tagged properties and methods (as indicated in the column -"API" above), but not for the rest of the class. +"API" below), but not for the rest of the class. + +To be on the safe side, check the following table to know which use cases are +covered by our backwards compatibility promise: + ++-----------------------------------------------+---------------+---------------+ +| Use Case | Regular | API | ++-----------------------------------------------+---------------+---------------+ +| If you... | Then we guarantee BC... | ++===============================================+===============+===============+ +| Type hint against the class | Yes | Yes | ++-----------------------------------------------+---------------+---------------+ +| Create a new instance | Yes | Yes | ++-----------------------------------------------+---------------+---------------+ +| Extend the class | Yes | Yes | ++-----------------------------------------------+---------------+---------------+ +| Access a public property | Yes | Yes | ++-----------------------------------------------+---------------+---------------+ +| Call a public method | Yes | Yes | ++-----------------------------------------------+---------------+---------------+ +| **If you extend the class and...** | **Then we guarantee BC...** | ++-----------------------------------------------+---------------+---------------+ +| Access a protected property | No [1]_ | Yes | ++-----------------------------------------------+---------------+---------------+ +| Call a protected methods | No [1]_ | Yes | ++-----------------------------------------------+---------------+---------------+ +| Override a public property | Yes | Yes | ++-----------------------------------------------+---------------+---------------+ +| Override a protected property | No [1]_ | Yes | ++-----------------------------------------------+---------------+---------------+ +| Override a public method | No [1]_ | Yes | ++-----------------------------------------------+---------------+---------------+ +| Override a protected method | No [1]_ | Yes | ++-----------------------------------------------+---------------+---------------+ +| Add a new property | No | No | ++-----------------------------------------------+---------------+---------------+ +| Add a new method | No | No | ++-----------------------------------------------+---------------+---------------+ +| Add a parameter to an overridden method | No [1]_ | Yes | ++-----------------------------------------------+---------------+---------------+ +| Add a default value to a parameter | Yes | Yes | ++-----------------------------------------------+---------------+---------------+ -Classes, properties and methods tagged with ``@internal`` should never be -created, extended or called directly. The same applies to all classes located in -the various ``*\\Tests\\`` namespaces. +.. note:: + If you think that one of our regular classes should have an ``@api`` tag, + put your request into a `new ticket on GitHub`_. We will then evaluate + whether we can add the tag or not. Working on Symfony Code ----------------------- @@ -137,7 +170,6 @@ Working on Symfony Code Do you want to help us improve Symfony? That's great! However, please stick to the rules listed below in order to ensure smooth upgrades for our users. - Changing Interfaces ~~~~~~~~~~~~~~~~~~~ @@ -166,7 +198,6 @@ Change parameter type Yes [2]_ [4]_ No Change return type Yes [2]_ [5]_ No ============================================== ============== ============== - Changing Classes ~~~~~~~~~~~~~~~~ @@ -226,7 +257,6 @@ Change parameter type Yes [2]_ [4]_ No Change return type Yes [2]_ [5]_ No ================================================== ============== ============== - .. [1] Your code may be broken by changes in the Symfony code. Such changes will however be documented in the UPGRADE file. From 25443c0341bf7973839a66d4d19b7b4d9ba114df Mon Sep 17 00:00:00 2001 From: Bernhard Schussek Date: Wed, 12 Feb 2014 11:13:15 +0100 Subject: [PATCH 31/39] Improved table formatting --- contributing/code/bc.rst | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/contributing/code/bc.rst b/contributing/code/bc.rst index 237555777f5..843ae65a4ad 100644 --- a/contributing/code/bc.rst +++ b/contributing/code/bc.rst @@ -58,9 +58,9 @@ backwards compatibility promise: +-----------------------------------------------+---------------+---------------+ | Use Case | Regular | API | -+-----------------------------------------------+---------------+---------------+ -| If you... | Then we guarantee BC... | +===============================================+===============+===============+ +| **If you...** | **Then we guarantee BC...** | ++-----------------------------------------------+---------------+---------------+ | Type hint against the interface | Yes | Yes | +-----------------------------------------------+---------------+---------------+ | Call a method | Yes | Yes | @@ -122,9 +122,9 @@ covered by our backwards compatibility promise: +-----------------------------------------------+---------------+---------------+ | Use Case | Regular | API | -+-----------------------------------------------+---------------+---------------+ -| If you... | Then we guarantee BC... | +===============================================+===============+===============+ +| **If you...** | **Then we guarantee BC...** | ++-----------------------------------------------+---------------+---------------+ | Type hint against the class | Yes | Yes | +-----------------------------------------------+---------------+---------------+ | Create a new instance | Yes | Yes | From 11bb8791724dd5b0738d2b87caaa4ef4ada9939d Mon Sep 17 00:00:00 2001 From: Bernhard Schussek Date: Wed, 12 Feb 2014 11:17:08 +0100 Subject: [PATCH 32/39] Grammar --- contributing/code/bc.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/contributing/code/bc.rst b/contributing/code/bc.rst index 843ae65a4ad..cacdace4f61 100644 --- a/contributing/code/bc.rst +++ b/contributing/code/bc.rst @@ -110,7 +110,7 @@ The difference between regular and API classes is that we guarantee full backwards compatibility if you extend an API class and override its methods. We can't give the same promise for regular classes, because there we may, for example, add an optional parameter to a method. Consequently, the signature of -your overridden method won't match anymore and generate a fatal error. +your overridden method wouldn't match anymore and generate a fatal error. In some cases, only specific properties and methods are tagged with the ``@api`` tag, even though their class is not. In these cases, we guarantee full backwards From fd1d912175687422921860b895fdb17af614e54e Mon Sep 17 00:00:00 2001 From: Bernhard Schussek Date: Wed, 12 Feb 2014 11:18:09 +0100 Subject: [PATCH 33/39] Typo --- contributing/code/bc.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/contributing/code/bc.rst b/contributing/code/bc.rst index cacdace4f61..bc613cafa04 100644 --- a/contributing/code/bc.rst +++ b/contributing/code/bc.rst @@ -139,7 +139,7 @@ covered by our backwards compatibility promise: +-----------------------------------------------+---------------+---------------+ | Access a protected property | No [1]_ | Yes | +-----------------------------------------------+---------------+---------------+ -| Call a protected methods | No [1]_ | Yes | +| Call a protected method | No [1]_ | Yes | +-----------------------------------------------+---------------+---------------+ | Override a public property | Yes | Yes | +-----------------------------------------------+---------------+---------------+ From bdd3c03b3c4eab265a4b280216bdcbf19fbf8608 Mon Sep 17 00:00:00 2001 From: Bernhard Schussek Date: Sat, 15 Feb 2014 14:32:42 +0100 Subject: [PATCH 34/39] Implemented changes suggested by @WouterJ --- contributing/code/bc.rst | 23 +++++++++++------------ 1 file changed, 11 insertions(+), 12 deletions(-) diff --git a/contributing/code/bc.rst b/contributing/code/bc.rst index bc613cafa04..f799673002e 100644 --- a/contributing/code/bc.rst +++ b/contributing/code/bc.rst @@ -2,10 +2,10 @@ Our Backwards Compatibility Promise =================================== If you are using Symfony, we promise you backwards compatibility (BC) for all -major releases (2.x, 3.x, ...). Ensuring smooth upgrades of your projects is our +minor releases (2.5, 2.6, etc.). Ensuring smooth upgrades of your projects is our first priority. However, backwards compatibility comes in many different flavors. -.. note:: +.. caution:: This promise was introduced with Symfony 2.3 and does not apply to previous versions of Symfony. @@ -29,10 +29,10 @@ All interfaces shipped with Symfony can be used in type hints. You can also call any of the methods that they declare. We guarantee that we won't break code that sticks to these rules. -.. note:: +.. caution:: The exception to this rule are interfaces tagged with ``@internal``. Such - interfaces should never be used or implemented. + interfaces should *never* be used or implemented. If you want to implement an interface, you should first make sure that the interface is an API interface. You can recognize API interfaces by the ``@api`` @@ -47,6 +47,8 @@ tag in their source code:: */ interface HttpKernelInterface { + // ... + } If you implement an API interface, we promise that we won't ever break your code. Regular interfaces, by contrast, should never be implemented, because if @@ -86,12 +88,12 @@ Using Our Classes All classes provided by Symfony may be instantiated and accessed through their public methods and properties. -.. note:: +.. caution:: Classes, properties and methods that bear the tag ``@internal`` as well as the classes located in the various ``*\\Tests\\`` namespaces are an - exception to this rule. They are meant for internal use only and should not - be accessed by your own code. + exception to this rule. They are meant for internal use only and should + *never* be accessed by your own code. Just like with interfaces, we also distinguish between regular and API classes. Like API interfaces, API classes are marked with an ``@api`` tag:: @@ -105,6 +107,8 @@ Like API interfaces, API classes are marked with an ``@api`` tag:: */ class Request { + // ... + } The difference between regular and API classes is that we guarantee full backwards compatibility if you extend an API class and override its methods. We @@ -304,13 +308,8 @@ Change return type Yes [2]_ [5]_ No previously generated a fatal error. .. _scalar type: http://php.net/manual/en/function.is-scalar.php - .. _boolean values: http://php.net/manual/en/function.boolval.php - .. _string values: http://www.php.net/manual/en/function.strval.php - .. _integer values: http://www.php.net/manual/en/function.intval.php - .. _float values: http://www.php.net/manual/en/function.floatval.php - .. _new ticket on GitHub: https://github.com/symfony/symfony/issues/new From 232090698e5b98c13bfcb0bbea0ea79b104e68c4 Mon Sep 17 00:00:00 2001 From: Bernhard Schussek Date: Sat, 15 Feb 2014 16:27:33 +0100 Subject: [PATCH 35/39] Extracted duplicated text into _api_tagging.rst.inc --- contributing/code/_api_tagging.rst.inc | 7 +++++++ contributing/code/bc.rst | 13 ++----------- 2 files changed, 9 insertions(+), 11 deletions(-) create mode 100644 contributing/code/_api_tagging.rst.inc diff --git a/contributing/code/_api_tagging.rst.inc b/contributing/code/_api_tagging.rst.inc new file mode 100644 index 00000000000..4cfd9363f6e --- /dev/null +++ b/contributing/code/_api_tagging.rst.inc @@ -0,0 +1,7 @@ +.. note:: + + If you think that one of our regular classes should have an ``@api`` tag, + put your request into a `new ticket on GitHub`_. We will then evaluate + whether we can add the tag or not. + +.. _new ticket on GitHub: https://github.com/symfony/symfony/issues/new diff --git a/contributing/code/bc.rst b/contributing/code/bc.rst index f799673002e..867b7ef3426 100644 --- a/contributing/code/bc.rst +++ b/contributing/code/bc.rst @@ -76,11 +76,7 @@ backwards compatibility promise: | Add a default value to a parameter | Yes | Yes | +-----------------------------------------------+---------------+---------------+ -.. note:: - - If you think that one of our regular interfaces should have an ``@api`` tag, - put your request into a `new ticket on GitHub`_. We will then evaluate - whether we can add the tag or not. +.. include:: _api_tagging.rst.inc Using Our Classes ~~~~~~~~~~~~~~~~~ @@ -162,11 +158,7 @@ covered by our backwards compatibility promise: | Add a default value to a parameter | Yes | Yes | +-----------------------------------------------+---------------+---------------+ -.. note:: - - If you think that one of our regular classes should have an ``@api`` tag, - put your request into a `new ticket on GitHub`_. We will then evaluate - whether we can add the tag or not. +.. include:: _api_tagging.rst.inc Working on Symfony Code ----------------------- @@ -312,4 +304,3 @@ Change return type Yes [2]_ [5]_ No .. _string values: http://www.php.net/manual/en/function.strval.php .. _integer values: http://www.php.net/manual/en/function.intval.php .. _float values: http://www.php.net/manual/en/function.floatval.php -.. _new ticket on GitHub: https://github.com/symfony/symfony/issues/new From 90c4de6e76a534f5279665e82e290477d9ad426c Mon Sep 17 00:00:00 2001 From: Bernhard Schussek Date: Thu, 20 Feb 2014 10:48:36 +0100 Subject: [PATCH 36/39] Mentioned Semantic Versioning in the introduction --- contributing/code/bc.rst | 37 ++++++++++++++++++++++++++++--------- 1 file changed, 28 insertions(+), 9 deletions(-) diff --git a/contributing/code/bc.rst b/contributing/code/bc.rst index 867b7ef3426..dee4306d2e9 100644 --- a/contributing/code/bc.rst +++ b/contributing/code/bc.rst @@ -1,26 +1,44 @@ Our Backwards Compatibility Promise =================================== -If you are using Symfony, we promise you backwards compatibility (BC) for all -minor releases (2.5, 2.6, etc.). Ensuring smooth upgrades of your projects is our -first priority. However, backwards compatibility comes in many different flavors. +Ensuring smooth upgrades of your projects is our first priority. That's why +we promise you backwards compatibility (BC) for all minor Symfony releases. + +You probably recognize this strategy as `Semantic Versioning`_. In short, +Semantic Versioning means that only major releases (such as 2.0, 3.0 etc.) are +allowed to break backwards compatibility. Minor releases (such as 2.5, 2.6 etc.) +may introduce new features, but must do so without breaking the existing API of +that release branch (2.x in the previous example). .. caution:: This promise was introduced with Symfony 2.3 and does not apply to previous versions of Symfony. -This page has two different target audiences: If you are using Symfony, it will -tell you how to make sure that you will be able to upgrade smoothly to all -future 2.x versions. If you are contributing to Symfony, this page will tell you -the rules that you need to follow to ensure smooth upgrades for our users. +However, backwards compatibility comes in many different flavors. In fact, almost +every change that we make to the framework can potentially break an application. +For example, if we add a new method to a class, this will break an application +which extended this class and added the same method, but with a different +method signature. + +Also, not every BC break has the same impact on application code. While some BC +breaks require you to make significant changes to your classes or your +architecture, others are fixed as easily as changing the name of a method. + +That's why we created this page for you. The section "Using Symfony Code" will +tell you how you can ensure that your application won't break completely when +upgrading to a newer version of the same major release branch. + +The second section, "Working on Symfony Code", is targeted at Symfony +contributors. This section lists detailed rules that every contributor needs to +follow to ensure smooth upgrades for our users. Using Symfony Code ------------------ If you are using Symfony in your projects, the following guidelines will help -you to ensure smooth upgrades to all future minor releases of Symfony (such as -2.5, 2.6 and so on). +you to ensure smooth upgrades to all future minor releases of your Symfony +version. Using Our Interfaces ~~~~~~~~~~~~~~~~~~~~ @@ -299,6 +317,7 @@ Change return type Yes [2]_ [5]_ No .. [7] A type hint may only be added if passing a value with a different type previously generated a fatal error. +.. _Semantic Versioning: http://semver.org/ .. _scalar type: http://php.net/manual/en/function.is-scalar.php .. _boolean values: http://php.net/manual/en/function.boolval.php .. _string values: http://www.php.net/manual/en/function.strval.php From be2251c877ae2c5778afa66d77f2241f193ab7cf Mon Sep 17 00:00:00 2001 From: Bernhard Schussek Date: Thu, 20 Feb 2014 11:09:19 +0100 Subject: [PATCH 37/39] Implemented @fabpot's comments --- contributing/code/bc.rst | 108 +++++++++++++++++++++++++-------------- 1 file changed, 71 insertions(+), 37 deletions(-) diff --git a/contributing/code/bc.rst b/contributing/code/bc.rst index dee4306d2e9..1ba1c218cb8 100644 --- a/contributing/code/bc.rst +++ b/contributing/code/bc.rst @@ -50,7 +50,7 @@ sticks to these rules. .. caution:: The exception to this rule are interfaces tagged with ``@internal``. Such - interfaces should *never* be used or implemented. + interfaces should not be used or implemented. If you want to implement an interface, you should first make sure that the interface is an API interface. You can recognize API interfaces by the ``@api`` @@ -69,9 +69,15 @@ tag in their source code:: } If you implement an API interface, we promise that we won't ever break your -code. Regular interfaces, by contrast, should never be implemented, because if -we add a new method to the interface or add a new optional parameter to the -signature of a method, we would generate a fatal error in your application. +code. Regular interfaces, by contrast, may be extended between minor releases, +for example by adding a new method. Be prepared to upgrade your code manually +if you implement a regular interface. + +.. note:: + + Even if we do changes that require manual upgrades, we limit ourselves to + changes that can be upgraded easily. We will always document the precise + upgrade instructions in the UPGRADE file in Symfony's root directory. The following table explains in detail which use cases are covered by our backwards compatibility promise: @@ -89,9 +95,9 @@ backwards compatibility promise: +-----------------------------------------------+---------------+---------------+ | Implement a method | No [1]_ | Yes | +-----------------------------------------------+---------------+---------------+ -| Add a parameter to an implemented method | No [1]_ | Yes | +| Add an argument to an implemented method | No [1]_ | Yes | +-----------------------------------------------+---------------+---------------+ -| Add a default value to a parameter | Yes | Yes | +| Add a default value to an argument | Yes | Yes | +-----------------------------------------------+---------------+---------------+ .. include:: _api_tagging.rst.inc @@ -107,7 +113,7 @@ public methods and properties. Classes, properties and methods that bear the tag ``@internal`` as well as the classes located in the various ``*\\Tests\\`` namespaces are an exception to this rule. They are meant for internal use only and should - *never* be accessed by your own code. + not be accessed by your own code. Just like with interfaces, we also distinguish between regular and API classes. Like API interfaces, API classes are marked with an ``@api`` tag:: @@ -127,9 +133,15 @@ Like API interfaces, API classes are marked with an ``@api`` tag:: The difference between regular and API classes is that we guarantee full backwards compatibility if you extend an API class and override its methods. We can't give the same promise for regular classes, because there we may, for -example, add an optional parameter to a method. Consequently, the signature of +example, add an optional argument to a method. Consequently, the signature of your overridden method wouldn't match anymore and generate a fatal error. +.. note:: + + As with interfaces, we limit ourselves to changes that can be upgraded + easily. We will document the precise ugprade instructions in the UPGRADE + file in Symfony's root directory. + In some cases, only specific properties and methods are tagged with the ``@api`` tag, even though their class is not. In these cases, we guarantee full backwards compatibility for the tagged properties and methods (as indicated in the column @@ -171,9 +183,13 @@ covered by our backwards compatibility promise: +-----------------------------------------------+---------------+---------------+ | Add a new method | No | No | +-----------------------------------------------+---------------+---------------+ -| Add a parameter to an overridden method | No [1]_ | Yes | +| Add an argument to an overridden method | No [1]_ | Yes | ++-----------------------------------------------+---------------+---------------+ +| Add a default value to an argument | Yes | Yes | ++-----------------------------------------------+---------------+---------------+ +| Call a private method (via Reflection) | No | No | +-----------------------------------------------+---------------+---------------+ -| Add a default value to a parameter | Yes | Yes | +| Access a private property (via Reflection) | No | No | +-----------------------------------------------+---------------+---------------+ .. include:: _api_tagging.rst.inc @@ -201,14 +217,14 @@ Remove parent interface No No Add method Yes [2]_ No Remove method No No Change name No No -Add parameter without a default value No No -Add parameter with a default value Yes [2]_ No -Remove parameter Yes [3]_ Yes [3]_ -Add default value to a parameter Yes [2]_ No -Remove default value of a parameter No No -Add type hint to a parameter No No -Remove type hint of a parameter Yes [2]_ No -Change parameter type Yes [2]_ [4]_ No +Add argument without a default value No No +Add argument with a default value Yes [2]_ No +Remove argument Yes [3]_ Yes [3]_ +Add default value to an argument Yes [2]_ No +Remove default value of an argument No No +Add type hint to an argument No No +Remove type hint of an argument Yes [2]_ No +Change argument type Yes [2]_ [4]_ No Change return type Yes [2]_ [5]_ No ============================================== ============== ============== @@ -236,8 +252,11 @@ Reduce visibility No No Add protected property Yes Yes Remove protected property Yes [2]_ No Reduce visibility Yes [2]_ No +**Private Properties** +Add private property Yes Yes +Remove private property Yes Yes **Constructors** -Add constructor without mandatory parameters Yes [2]_ Yes [2]_ +Add constructor without mandatory arguments Yes [2]_ Yes [2]_ Remove constructor Yes [2]_ No Reduce visibility of a public constructor No No Reduce visibility of a protected constructor Yes [2]_ No @@ -246,29 +265,43 @@ 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 [2]_ No -Remove parameter Yes [3]_ Yes [3]_ -Add default value to a parameter Yes [2]_ No -Remove default value of a parameter No No -Add type hint to a parameter Yes [7]_ No -Remove type hint of a parameter Yes [2]_ No -Change parameter type Yes [2]_ [4]_ No +Add argument without a default value No No +Add argument with a default value Yes [2]_ No +Remove argument Yes [3]_ Yes [3]_ +Add default value to an argument Yes [2]_ No +Remove default value of an argument No No +Add type hint to an argument Yes [7]_ No +Remove type hint of an argument Yes [2]_ No +Change argument type Yes [2]_ [4]_ No Change return type Yes [2]_ [5]_ No **Protected Methods** Add protected method Yes Yes Remove protected method Yes [2]_ No Change name No No Reduce visibility Yes [2]_ No -Add parameter without a default value Yes [2]_ No -Add parameter with a default value Yes [2]_ No -Remove parameter Yes [3]_ Yes [3]_ -Add default value to a parameter Yes [2]_ No -Remove default value of a parameter Yes [2]_ No -Add type hint to a parameter Yes [2]_ No -Remove type hint of a parameter Yes [2]_ No -Change parameter type Yes [2]_ [4]_ No +Add argument without a default value Yes [2]_ No +Add argument with a default value Yes [2]_ No +Remove argument Yes [3]_ Yes [3]_ +Add default value to an argument Yes [2]_ No +Remove default value of an argument Yes [2]_ No +Add type hint to an argument Yes [2]_ No +Remove type hint of an argument Yes [2]_ No +Change argument type Yes [2]_ [4]_ No Change return type Yes [2]_ [5]_ No +**Private Methods** +Add private method Yes Yes +Remove private method Yes Yes +Change name Yes Yes +Reduce visibility Yes Yes +Add argument without a default value Yes Yes +Add argument with a default value Yes Yes +Remove argument Yes Yes +Add default value to an argument Yes Yes +Remove default value of an argument Yes Yes +Add type hint to an argument Yes Yes +Remove type hint of an argument Yes Yes +Change argument type Yes Yes +Change return type Yes Yes ================================================== ============== ============== .. [1] Your code may be broken by changes in the Symfony code. Such changes will @@ -277,9 +310,10 @@ Change return type Yes [2]_ [5]_ No .. [2] Should be avoided. When done, this change must be documented in the UPGRADE file. -.. [3] Only the last parameter(s) of a method may be removed. +.. [3] Only the last argument(s) of a method may be removed, as PHP does not + care about additional arguments that you pass to a method. -.. [4] The parameter type may only be changed to a compatible or less specific +.. [4] The argument type may only be changed to a compatible or less specific type. The following type changes are allowed: =================== ================================================================== From ce58ee9ea6a40a4e59e85568d7829c87169aae47 Mon Sep 17 00:00:00 2001 From: Bernhard Schussek Date: Thu, 20 Feb 2014 11:18:41 +0100 Subject: [PATCH 38/39] Added rules for adding parent interfaces and moving methods/properties to parent interfaces/classes --- contributing/code/bc.rst | 45 ++++++++++++++++++++++++---------------- 1 file changed, 27 insertions(+), 18 deletions(-) diff --git a/contributing/code/bc.rst b/contributing/code/bc.rst index 1ba1c218cb8..e4168b737f8 100644 --- a/contributing/code/bc.rst +++ b/contributing/code/bc.rst @@ -4,7 +4,7 @@ Our Backwards Compatibility Promise Ensuring smooth upgrades of your projects is our first priority. That's why we promise you backwards compatibility (BC) for all minor Symfony releases. -You probably recognize this strategy as `Semantic Versioning`_. In short, +You probably recognize this strategy as `Semantic Versioning`_. In short, Semantic Versioning means that only major releases (such as 2.0, 3.0 etc.) are allowed to break backwards compatibility. Minor releases (such as 2.5, 2.6 etc.) may introduce new features, but must do so without breaking the existing API of @@ -211,21 +211,22 @@ Type of Change Regular API ============================================== ============== ============== Remove entirely No No Change name or namespace No No -Add parent interface Yes [2]_ No +Add parent interface Yes [2]_ Yes [3]_ Remove parent interface No No **Methods** Add method Yes [2]_ No Remove method No No Change name No No +Move to parent interface Yes Yes Add argument without a default value No No Add argument with a default value Yes [2]_ No -Remove argument Yes [3]_ Yes [3]_ +Remove argument Yes [4]_ Yes [4]_ Add default value to an argument Yes [2]_ No Remove default value of an argument No No Add type hint to an argument No No Remove type hint of an argument Yes [2]_ No -Change argument type Yes [2]_ [4]_ No -Change return type Yes [2]_ [5]_ No +Change argument type Yes [2]_ [5]_ No +Change return type Yes [2]_ [6]_ No ============================================== ============== ============== Changing Classes @@ -241,17 +242,19 @@ Remove entirely No No Make final Yes [2]_ No Make abstract No No Change name or namespace No No -Change parent class Yes [6]_ Yes [6]_ +Change parent class Yes [7]_ Yes [7]_ Add interface Yes Yes Remove interface No No **Public Properties** Add public property Yes Yes Remove public property No No Reduce visibility No No +Move to parent class Yes Yes **Protected Properties** Add protected property Yes Yes Remove protected property Yes [2]_ No Reduce visibility Yes [2]_ No +Move to parent class Yes Yes **Private Properties** Add private property Yes Yes Remove private property Yes Yes @@ -260,34 +263,37 @@ Add constructor without mandatory arguments Yes [2]_ Yes [2]_ Remove constructor Yes [2]_ No Reduce visibility of a public constructor No No Reduce visibility of a protected constructor Yes [2]_ No +Move to parent class Yes Yes **Public Methods** Add public method Yes Yes Remove public method No No Change name No No Reduce visibility No No +Move to parent class Yes Yes Add argument without a default value No No Add argument with a default value Yes [2]_ No -Remove argument Yes [3]_ Yes [3]_ +Remove argument Yes [4]_ Yes [4]_ Add default value to an argument Yes [2]_ No Remove default value of an argument No No -Add type hint to an argument Yes [7]_ No +Add type hint to an argument Yes [8]_ No Remove type hint of an argument Yes [2]_ No -Change argument type Yes [2]_ [4]_ No -Change return type Yes [2]_ [5]_ No +Change argument type Yes [2]_ [5]_ No +Change return type Yes [2]_ [6]_ No **Protected Methods** Add protected method Yes Yes Remove protected method Yes [2]_ No Change name No No Reduce visibility Yes [2]_ No +Move to parent class Yes Yes Add argument without a default value Yes [2]_ No Add argument with a default value Yes [2]_ No -Remove argument Yes [3]_ Yes [3]_ +Remove argument Yes [4]_ Yes [4]_ Add default value to an argument Yes [2]_ No Remove default value of an argument Yes [2]_ No Add type hint to an argument Yes [2]_ No Remove type hint of an argument Yes [2]_ No -Change argument type Yes [2]_ [4]_ No -Change return type Yes [2]_ [5]_ No +Change argument type Yes [2]_ [5]_ No +Change return type Yes [2]_ [6]_ No **Private Methods** Add private method Yes Yes Remove private method Yes Yes @@ -310,10 +316,13 @@ Change return type Yes Yes .. [2] Should be avoided. When done, this change must be documented in the UPGRADE file. -.. [3] Only the last argument(s) of a method may be removed, as PHP does not +.. [3] The added parent interface must not introduce any new methods that don't + exist in the interface already. + +.. [4] Only the last argument(s) of a method may be removed, as PHP does not care about additional arguments that you pass to a method. -.. [4] The argument type may only be changed to a compatible or less specific +.. [5] The argument type may only be changed to a compatible or less specific type. The following type changes are allowed: =================== ================================================================== @@ -327,7 +336,7 @@ Change return type Yes Yes interface ```` any superinterface of ```` =================== ================================================================== -.. [5] The return type may only be changed to a compatible or more specific +.. [6] The return type may only be changed to a compatible or more specific type. The following type changes are allowed: =================== ================================================================== @@ -345,10 +354,10 @@ Change return type Yes Yes interface ```` any subinterface or implementing class of ```` =================== ================================================================== -.. [6] When changing the parent class, the original parent class must remain an +.. [7] When changing the parent class, the original parent class must remain an ancestor of the class. -.. [7] A type hint may only be added if passing a value with a different type +.. [8] A type hint may only be added if passing a value with a different type previously generated a fatal error. .. _Semantic Versioning: http://semver.org/ From 0717192a561ac497b0d41a348c9872f349cbf963 Mon Sep 17 00:00:00 2001 From: Bernhard Schussek Date: Thu, 20 Feb 2014 11:24:29 +0100 Subject: [PATCH 39/39] Removed useless line break --- contributing/code/bc.rst | 1 - 1 file changed, 1 deletion(-) diff --git a/contributing/code/bc.rst b/contributing/code/bc.rst index e4168b737f8..e124f8b8ba6 100644 --- a/contributing/code/bc.rst +++ b/contributing/code/bc.rst @@ -3,7 +3,6 @@ Our Backwards Compatibility Promise Ensuring smooth upgrades of your projects is our first priority. That's why we promise you backwards compatibility (BC) for all minor Symfony releases. - You probably recognize this strategy as `Semantic Versioning`_. In short, Semantic Versioning means that only major releases (such as 2.0, 3.0 etc.) are allowed to break backwards compatibility. Minor releases (such as 2.5, 2.6 etc.)