This document discusses Magento's policy and approach to backward compatibility. It provides an overview of Magento's versioning strategy and semantic versioning. It outlines the rules for dependency management and prohibited code changes to maintain backward compatibility. The key points are that Magento aims to balance backward compatibility fixes with code quality improvements, and that backward compatibility is prioritized over implementation effort. Backward compatible changes should be implemented following best practices to maintain clean code.

1. Page | 1© 2017 Magento, Inc.
Backward Compatibility

2. Page | 2© 2017 Magento, Inc.
Oleksii Korshenko
Software Architect, Magento 2

3. Why Backward
Compatibility?

4. Page | 4© 2017 Magento, Inc.
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.13 – February 16, 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.1.6 – March 27, 2017
• …..
• 2.2.0 - TBD
20 patch releases, 1 minor release

5. Page | 5© 2017 Magento, Inc.
For merchants
cost-effective process
For developers –
forward-compatible extensions
Why does Backward Compatibility matter?

6. Page | 6© 2017 Magento, Inc.
Does Magento have a lot of bugs?

7. Page | 7© 2017 Magento, Inc.
Are these bugs annoying
for Magento developers?

8. Page | 8© 2017 Magento, Inc.
Keep Magento backwards compatible
vs.
fixing its flaws?

9. Page | 9© 2017 Magento, Inc.
We MUST do BOTH

10. Page | 10© 2017 Magento, Inc.
Backward Compatible Fix
*it works (most of the time), but code quality
is far from good enough

11. Backward compatibility (BC)
policy for Magento code

12. Page | 12© 2017 Magento, Inc.
Semantic Versioning
Product Version
Minor Patch .
2 . 1 . 4
100 . 1 . 4
Major Minor Patch
Module Version
MAJOR . MINOR . PATCH

13. Page | 13© 2017 Magento, Inc.
Public vs Private code
Public – has @api annotation
Private – no @api annotation

14. Page | 14© 2017 Magento, Inc.
What examples of Public code Magento has?
• Class/Interfaces (PHP, Javascript)
• XML configuration
• Events
• ….
Full list is on the DevDocs: Versioning and compatibility
http://devdocs.magento.com/guides/v2.1/extension-dev-guide/versioning/index.html

15. Page | 15© 2017 Magento, Inc.
API vs SPI (Extension Points)
A PHP Interface usages:
• As an API
• As a Service Provider Interface (SPI)
• As both

16. Page | 16© 2017 Magento, Inc.
API vs SPI (Extension Points)
Who decides whether interface/class
belong to API or SPI?
YOU

17. Dependency Rules

18. Page | 18© 2017 Magento, Inc.
Rule #1
Dependency Rules
Usage Dependency
Calls API MAJOR
"require": {
"magento/module-customer": "100.*.*"
}

19. Page | 19© 2017 Magento, Inc.
Rule #2
Dependency Rules
Usage Dependency
Uses SPI MAJOR+MINOR
"require": {
"magento/module-customer": "100.5.*"
}

20. Page | 20© 2017 Magento, Inc.
Rule #3
Dependency Rules
Usage Dependency
Uses
private code
MAJOR+MINOR+PATCH
"require": {
"magento/module-customer": "100.5.2"
}

21. Prohibited Code Changes

22. Page | 22© 2017 Magento, Inc.
Prohibited Code Changes. PHP
2. Public/protected method removal
1. Interface/class removal
3. Introduction of a method to a class/interface

23. Page | 23© 2017 Magento, Inc.
Prohibited Code Changes. PHP
5. Parameter addition in protected methods
4. Parameter addition in public methods
6. Method argument type modification

24. Page | 24© 2017 Magento, Inc.
Allowed constructor modifications
class ExistingClass
{
private $newDependency;
public function __construct(
OldDependencyIntreface $oldDependency,
$oldRequiredConstructorParameter,
$oldOptinalConstructorParameter = null,
NewDependencyInterface $newDependency = null
) {
...
$this>newDependency = $newDependency ?: MagentoFrameworkAppObjectManager::getInstance()
->get(NewDependencyInterface::class);
...
}
public function existingFunction()
{
// Use $this->newDependency wherever the new dependency is needed
}
}

25. Page | 25© 2017 Magento, Inc.
Keep backward compatibility in:

26. Page | 26© 2017 Magento, Inc.
The main rule of backwards compatibility
Backwards compatibility is more important
than
effort of the implementation

27. Page | 27© 2017 Magento, Inc.
Do all backward
compatible fixes
look ugly?

28. Page | 28© 2017 Magento, Inc.
This is how Backward Compatible
fix should look like
http://devdocs.magento.com/guides/v2.1/ext-best-practices/extension-coding/backwards-compatible-development/index.html

29. Q & A
@okorshenko