Codebase changes

Every Magento version release include 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.

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 or change private code. If this is unavoidable, you must depend on the patch version of the core modules used.

API and customization points

Public code includes Public API(indicated by the @api docblock tag) and Public 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 customize or replace Customization Points to customize existing application scenarios. Modifications that break Customization Points will trigger an increase in a module’s MINOR version.

An interface or a virtual type represent either an API or 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 on a MINOR release indicates that Magento plans to remove that code in a future MINOR release.

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

Deprecated Code Example

/**
 * @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.