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 |