Oleksii Korshenko - Magento 2 Backwards Compatible Policy

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

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

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).

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.

Oleksii Korshenko - Magento 2 Backwards Compatible Policy

Meet Magento Italy

Oleksii Korshenko - Magento 2 Backwards Compatible Policy