Codebase changes

Every Magento version release includes a change in the codebase. The scope of the change determines whether the MAJOR, MINOR, or PATCH number increases in the version.

Public vs private code changes

A Magento module’s codebase consists of public and private code. Public code includes Public API(indicated by the @api docblock tag) and Public Customization Points. All other code is considered private.

Changes in public code always trigger MINOR or MAJOR version increases.

In most cases, modifications to private code will trigger PATCH version increases. On rare occasions, if the Magento development team made significant modifications to private code, they will increase the MINOR or MAJOR version.

Third-party modules should not use private code. If this is unavoidable, you must depend on the PATCH version of the core modules used.

API and customization points

Modules call APIs to create new application scenarios. Modifications that break the API will trigger an increase in a module’s MAJOR version.

Modules use Customization Points to customize existing application scenarios. Modifications that break Customization Points will trigger an increase in a module’s MINOR version.

An interface represents either an API or a Customization Point.

This policy allows third-party module developers to declare more granular dependencies depending on their module’s interaction with Magento modules.

Deprecation

Marking public code with @deprecated indicates that Magento plans to remove that code in a future MINOR release.

When Magento deprecates the API or a customization point in favor of a new implementation, the @see annotation points to the new implementation.

Deprecated Code Example:

1
2
3
4
5
6
7
8
9
/**
 * @deprecated since 2.1.0
 * @see \Magento\Framework\Model\ResourceModel\Db\AbstractDb::save()
 */
public function save()
{
    // ...
}

Version increase scenarios

This table lists code change scenarios and which version number it affects. Use this table to understand what changes Magento can make and which version number gets increased for that change. Any change not listed below is considered a PATCH level change.

PHP Classes Intended for Extension

Though inheritance is discouraged in Magento, the following classes are still acceptable for extension at the moment:

• \Magento\Framework\Model\AbstractExtensibleModel
• \Magento\Framework\Api\AbstractExtensibleObject
• \Magento\Framework\Api\AbstractSimpleObject
• \Magento\Framework\Model\AbstractModel
• \Magento\Framework\App\Action\Action
• \Magento\Backend\App\Action
• \Magento\Backend\App\AbstractAction
• \Magento\Framework\App\Action\AbstractAction
• \Magento\Framework\View\Element\AbstractBlock
• \Magento\Framework\View\Element\Template

As Magento framework improves, this list should be reduced and, eventually, eliminated.