Our Backward Compatibility Promise
Code Compatibility Promise
In compliance with our Release Process and to ensure seamless upgrades, we promise the following:
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).
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.
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/)Other code related to tests (located in
*/Test/)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 |