Since publishing Magento 2.0.0 on November 2015, we’ve extended the codebase with sixteen 2.x patch releases and 1 minor release. We understand that the Magento 2.x upgrade process is challenging and can raise compatibility issues for extension developers. To simplify this upgrade process, the Magento 2 development team has prepared a Backward Compatibility policy, which is specifically focused on minimizing compatibility issues with Magento 2 extensions. In this presentation, we has discussed Magento’s 2.x Backward Compatibility policy. We has identified the code that you can rely on during extension development, as well as the parts of Magento 2.x codebase where we might introduce breaking changes in upcoming patch or minor releases. We also has shared our best practices for how to optimally configure dependencies on Magento 2.x packages to improve the compatibility of your extensions.

1. © 2017 Magento, Inc. All rights reserved.

2. © 2017 Magento, Inc. Page | 2
History. First Release. Magento 2 RC. November 5, 2015
#1. Dev. Manager
#4. QA Manager
#3. Director of M2#2. Lead M2 Architect
#5. VP of M2 Technology
(making a photo)
Developer
5 Managers + 1 Developer = One Magento 2 release

3. © 2017 Magento, Inc. Page | 3
Where we are…
 2.0.0 – November 16, 2015
 2.0.1 – January 19, 2016
 …..
 2.0.8 – July 18, 2016
 2.0.9 – August 3, 2016
 2.0.10 – October 7, 2016
 2.0.11 – December 13, 2016
 2.0.12 – January 27, 2017
 2.0.15 – February 13, 2017
 2.1.0 – June 23, 2016
 2.1.1 – August 25, 2016
 2.1.2 – October 10, 2016
 2.1.3 – December 8, 2016
 2.1.4 – January 23, 2017
 2.1.5 – February 15, 2017
 …..
 2.2.0 - TBD
Minor Release
Minor Release
20 patch releases, 1 minor release

4. © 2017 Magento, Inc. Page | 4© 2017 Magento, Inc. Page | 4
1 Platform Version vs Module Version

5. © 2017 Magento, Inc. Page | 5
Platform Version vs Module Version
A Platform Patch Release can trigger an increase in the PATCH
version of the module.
Platform Version
Minor Patch .
2 . 1 . 4
100 . 1 . 4
Major Minor Patch
Module Version
A Platform Minor Release can trigger an increase in the MINOR or
MAJOR version of the module.
Note: In exceptional cases, we can increase the MINOR version of the
module in the scope of a PATCH platform release.
For example: magento/module-vault version was changed from
100.1.1 to 100.2.0 in the scope of the Magento 2.1.3 release (added
new method to API interface).

6. © 2017 Magento, Inc. Page | 6
Platform Version vs Module Version
Module Name Release 2.0.0-rc Release 2.0.12 Release 2.1.0 Release 2.1.4
Catalog 100.0.0 100.0.12 101.0.0 101.0.4
Checkout 100.0.0 100.0.11 100.1.0 100.1.4
CMS 100.0.0 100.0.5 101.0.0 101.0.3
Customer 100.0.0 100.0.10 100.1.0 100.1.4
Sales 100.0.0 100.0.12 100.1.0 100.1.4
Platform Version
2 . 1 . 4
Minor Patch
Module Version
100 . 1 . 4
Major Minor Patch

7. © 2017 Magento, Inc. Page | 7© 2017 Magento, Inc. Page | 7
2 The Code

8. © 2017 Magento, Inc. Page | 8
The Code
Public vs Private code
• Private code should not be used by third-party
modules.
• Modifications will trigger only PATCH version bumps.
• Significant changes to private code of a module will
trigger a bump to its MINOR or MAJOR number.
Private Code
• Public code may consist of Public API (Application
Programming Interface) and public customization
points.
• Changes to public code always trigger MINOR or
MAJOR version bumps.
Public Code

9. © 2017 Magento, Inc. Page | 9
PHP Interfaces/Classes (marked with @api)
 inject in constructor and/or call
methods
 add a plugin to class/interface
 extend from abstract class
 configure class preference
in di.xml
 configure constructor argument
in di.xml
 implement interface
 redefine interface preference
in di.xml
Dependency on MAJOR version Dependency on MINOR version
100 . 1 . *
Major Minor Patch
100 . * . *
Major Minor Patch
API and Customization Points: Part I

10. © 2017 Magento, Inc. Page | 10
The Code
API and Customization Points: Part II
API Version of dependency Code change
Events triggered by component
(both static & dynamic)
subscribe to event - MAJOR • removed event argument
• removed event
Layout handles declared by modules • add block instance – MAJOR
• move/remove blocks and containers –
MAJOR
• new layout page handle – MINOR
• new container/block added to handle
– MINOR
• removed/renamed container/block -
MAJOR
• removed layout handle - MAJOR
XML configuration type • provide additional configuration to the
configuration type – MAJOR
• extend existing XSD - MINOR
• renamed/removed schema file or
configuration type - MAJOR
• added obligatory node/attribute
• removed node/attribute - MAJOR
• add new optional node/attribute -
MINOR
Structure of system configuration • configure module through system
configuration values – MAJOR
• read system configuration using
config path - MAJOR
• removed/renamed config path -
MAJOR

11. © 2017 Magento, Inc. Page | 11
Module Dependency Rules
Core module dependency rules
1. Specify a dependency on all used modules in the 'require' section of the
module’s composer.json file.
2. Specify a dependency only on used modules, not on meta packages ('product-
community-edition').
3. Specify the MAJOR and/or MINOR version number of a used module if the module API
or customization points are used.
4. Specify the MAJOR, MINOR, and PATCH versions of a used module if the module
private code is used (called or customized).

12. © 2017 Magento, Inc. Page | 12© 2017 Magento, Inc. Page | 12
3 Code Deprecation

13. © 2017 Magento, Inc. Page | 13
Code Deprecation
Deprecation Example
• We will remove deprecated @api code only in the next minor product version.
• If we are deprecating an API or customization point in favor of a new implementation, we will add
suggested implementation in @see annotation.

14. © 2017 Magento, Inc. Page | 14
Code Deprecation
Deprecation use cases (@api and not @api)
http://devdocs.magento.com/guides/v2.1/extension-dev-guide/backward-compatibility.html
PHP use cases Alternative implementation
interface/class removal Mark with @deprecated tag instead of removing it. Also mark all its methods as
deprecated.
public & protected method
removal
Mark with @deprecated tag instead.
Continue returning the same results from the method if possible, so the old
functionality is preserved.
constructor modification Add the new optional parameter to the constructor at the end of the arguments
list. Fetch the dependency from ObjectManager
Mark as @deprecated any outdated constructor arguments.
public & protected property
removal
Mark with @deprecated tag instead.
Continue storing the value in the property, if possible, so the old functionality is
preserved.

15. © 2017 Magento, Inc. Page | 15
Magento 2 Backward Compatible Policy
Thank you!