Codebase changes

Every 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 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 Adobe 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 core modules.

Deprecation

Marking public code with @deprecated indicates that Adobe plans to remove that code in a future MINOR release or potentially after a year if no MINOR version is released.

When Adobe 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 Adobe 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, the following classes are still acceptable for extensions 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 the framework improves, this list should be reduced and, eventually, eliminated.

Related topics

• Release policy
• Upcoming releases
• Backward compatibility policy