Our Backward Compatibility Promise

Code Compatibility Promise

In compliance with our Release Process and to ensure seamless upgrades, we promise the following:

  1. MAJOR and MINOR releases MAY introduce backward-incompatible changes. MAJOR, MINOR, and PATCH are SemVer terms that describe release versions (e.g., 2.1.4), where 2 is a MAJOR, 1 is a MINOR, and 4 is a PATCH release (MAJOR.MINOR.PATCH).
  2. Internal implementation and some parts of the logic MAY be changed even in PATCH releases, however, they should preserve the external interface following the instructions provided below.
  3. At the same time, backward-incompatible changes (marked as “No” in the table below) in the PATCH release SHOULD NOT replace the existing logic. Instead, they SHOULD be marked as deprecated, and a new implementation should be added instead.

Code Covered

This BC promise applies to all PHP code except for:

  • PHPUnit tests (located in */Tests/Unit/)
  • Behat tests (located in */Tests/Behat/)
  • Functional tests (located in */Tests/Functional/)
  • Bundles with the testing framework extensions and demo data definitions */Bundle/TestFrameworkBundle/, */Bundle/TestFrameworkCRMBundle/, */Bundle/DemoDataBundle/, */Bundle/DemoDataCommerceCRMBundle/
  • An enterprise package with additional OroCRM demo data oro/crm-pro-demo-data-bundle

BC Exceptions

Backward compatibility can be ignored in security bug fixes or critical bugs. In this case, all the incompatible changes are described in the CHANGELOG.md in a corresponding package.

Using Code

Changing Interfaces

This table specifies the changes you are allowed to do when working on interfaces:

Type of Change Change Allowed
Add an interface Yes
Remove an interface No
Add a method No
Remove a method No
Add an argument to a method No
Methods  
Change an argument name Yes
Remove an argument No
Add a type hint to an argument No
Remove a type hint of an argument No
Add a default value to an argument No
Remove a default value of an argument No
Change an argument default value No

Changing Classes

This table specifies the changes you are allowed to do when working on classes:

Type of Change Change Allowed
Remove the class entirely No
Add a class Yes
Public Properties  
Remove public property No
Add public property Yes
Protected Properties  
Remove protected property No
Add protected property Yes
Private Properties  
Add private property Yes
Remove private property Yes
Constructors  
New public constructor (does not match supertype) No
New protected constructor (does not match supertype) No
Public Methods  
Remove a public method No
Add an argument No
Remove an argument No
Add a public method Yes
Change an argument name Yes
Add a type hint to an argument No
Remove a type hint of an argument No
Add a default value to an argument No
Remove a default value of an argument No
Change a default value of an argument No
Protected Methods  
Remove a protected method No
Add an argument No
Remove an argument No
Add a protected method Yes
Change an argument name Yes
Add a type hint to an argument No
Remove a type hint of an argument No
Add a default value to an argument No
Remove a default value of an argument No
Change a default value of an argument No
Private Methods  
Add a private method Yes
Remove a private method Yes
Add an argument Yes
Remove an argument Yes
Change an argument name Yes
Add a type hint to an argument Yes
Remove a type hint of an argument Yes
Add a default value to an argument Yes
Remove a default value of an argument Yes
Change a default value of an argument Yes
Final classes  
Add a public method Yes
Add a protected method Yes
Add an argument to a protected method Yes
Remove a protected method Yes
Change a public method implementation Yes
Change a protected method implementation Yes
Change a private method implementation Yes

Changing Traits

This table specifies the changes you are allowed to do when working on traits:

Type of Change Change Allowed
Remove a trait entirely No
Add a trait Yes
Remove a public method No
Add a public method Yes
Remove a protected method No
Add a protected method Yes
Remove protected property No
Add protected property Yes
Add private property Yes
Remove private property No
Add a private method Yes
Remove a private method No
Add an argument to a public method No
Add an argument to a protected method No
Add an argument to a private method No
Add public property Yes
Change a public method implementation Yes
Change a protected method implementation Yes
Change a private method implementation Yes
Change an argument name of (public, protected, private) Yes
Remove an argument of (public, protected, private) No
Add a type hint of an argument (public, protected, private) No
Remove a type hint of an argument (public, protected, private) No
Add a default argument value (public, protected, private) No
Remove a default argument value (public, protected, private) No
Change a default argument value (public, protected, private) No

Changing Functions

This table specifies the changes you are allowed to do when working on functions:

Type of Change Change Allowed
Remove a function No
Add a new argument No
Remove an argument No
Add a function No
Change a function implementation Yes
Remove an argument type No
Add a default value to an argument No
Remove a default value of an argument No
Change a default value of an argument No