Backward Compatibility Developer's Guide in Magento 2. #MM17CZ

© 2016 Magento, Inc. Page | 1
Backward Compatibility
Developer’s guide
Miniailo Igor,
Magento 2 Architect

• Magento 2 Technical Guidelines
• Versioning
• Backward Compatibility Development
Guide

Why does BC matter?
For merchants, the process
must be cost-effective, while
developers want their
extensions to be forward-
compatible for as long as
possible.

Does Magento have a lot of bugs?
Are these bugs annoying for Magento
developers?

Keep Magento backwards compatible vs.
fixing its flaws?

We MUST do BOTH

Backward Compatible Fix
*it works (most of the time), but code quality
is far from good enough

Backward compatibility (BC)
policy for Magento code

Semantic Versioning
Version numbers are in the format
MAJOR.MINOR.PATCH, where:
– MAJOR indicates incompatible API changes
– MINOR indicates backward-compatible
functionality has been added
– PATCH indicates backward-compatible bug
fixes

The backward compatibility policy
applies to PHP code annotated with
@api

Public and Private code

Public vs Private code
Private code is not supposed to
be used by third party modules,
so, in most cases, its
modifications will only trigger
PATCH version bumps.
Changes in public code always
trigger MINOR or MAJOR
version bumps.

What examples of Public code Magento has?
• PHP Interface (marked with @api)
• PHP Class (marked with @api)
• Javascript Interface (marked with @api)
• Javascript Class (marked with @api)
• Virtual Type (marked with @api)
• URL paths
• Console commands and their arguments
• Less Variables & Mixins
• Message queue topics and their data types
• UI component declarations
• Layout handles declared by modules
• Events triggered by component (both static dynamic)
• Schema of configuration types introduced by module
• Structure of System Configuration fields used by module

API vs SPI (Extension Points)
A PHP Interface in Magento can be used several ways by the core
product and extension developers.
• As an API. An interface is called by PHP code.
• As a Service Provider Interface (SPI). An interface can
be implemented, allowing code to provide functionality to
the platform.
• As both. APIs and SPIs are not mutually exclusive.
Therefore, we do not distinguish them separately. SPIs
are annotated the same as APIs.

Who decides whether interface/class belong to API or SPI?
YOU

Dependency Rules API
If a module uses (calls) an API, it should be dependent on the MAJOR
version.
API dependency example
{
...
"require": {
"magento/module-customer": "~100.0", // (>=100.0 <101.0.0)
},
...
}

Dependency Rules SPI
If a module implements an API/SPI, it should be dependent on the
MAJOR+MINOR version.
SPI dependency example
{
...
"require": {
"magento/module-customer": "~100.0.0", // (>=100.0.0 <100.1.0)
},
...
}

http://devdocs.magento.com/guides/v2.1/release-notes/backward-
incompatible-changes-2.1.html

What keeps us from making mistakes?
To minimize this risk we have developed a tool Semantic
Version Checker Tool that analyzes two code bases and
determines what part of the version need updating
(MAJOR, MINOR, PATCH). As part of the delivery process,
we must run this tool and use the results for input to the
Version Setter tool.

Prohibited Code Changes

• Interface/class removal
• Public & protected method removal
• Introduction of a method to a class or
interface
PHP - Prohibited Code Changes

• Static function removal
• Parameter addition in public methods
• Parameter addition in protected
methods

• Method argument type modification
• Modification of types of thrown
exceptions (unless a new exception is
a subtype of the old one)
• Constructor modification

class ExistingClass
{
/**
* @var NewDependencyInterface $newDependency
*/
private $newDependency;
public function __construct(
OldDependencyIntreface $oldDependency,
$oldRequiredConstructorParameter,
$oldOptinalConstructorParameter = null,
NewDependencyInterface $newDependency = null
) {
...
$this>newDependency = $newDependency ?: MagentoFrameworkAppObjectManager::getInstance()
->get(NewDependencyInterface::class);
...
}
public function existingFunction() {
// Existing functionality
...
// Use $this->newDependency wherever the new dependency is needed
...
}
}

The main rule is that backwards compatibility
is more important than niceness and effort of
the implementation.

Do all backward
compatible fixes look
ugly because we are not
allowed to make
refactoring?

Coupling Between Objects Reaches Its Limit with
a New Dependency

We MUST do continuous Refactoring!
Backward Compatibility should not be an excuse
for not doing refactoring!

This is how Backward
Compatible fix should
look like

Q & A
@iminyaylo

Backward Compatibility Developer's Guide in Magento 2. #MM17CZ

More Related Content

What's hot

Similar to Backward Compatibility Developer's Guide in Magento 2. #MM17CZ

More from Igor Miniailo

Recently uploaded

Backward Compatibility Developer's Guide in Magento 2. #MM17CZ

Editor's Notes