Edit in GitHubLog an issue

Code 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:

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

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.

API/Customization PointCode ChangeVersion Change
PHP Interface (marked with @api)New interfaceMINOR
New method addedMINOR
Interface removedMAJOR
Method removedMAJOR
New required method argumentMAJOR
New optional method argumentMAJOR
Removed the last argument for a methodMINOR
Changed a method signature (excluding last argument removal)MAJOR
New method exception (excluding subtypes of existing exceptions)MAJOR
New method exception (subtypes of an existing one)PATCH
PHP Class (marked with @api)New ClassMINOR
New method addedMINOR
Class removedMAJOR
Method removedMAJOR
New required method argumentMAJOR
New optional method argumentMINOR
Removed a non-last argumentMAJOR
New required constructor object argumentMINOR
New optional constructor argument in a class intended for extensionMINOR
New optional constructor argument in a class not intended for extensionPATCH
New required constructor scalar argument (without pre-configured value)MAJOR
Removed a non-last constructor argumentMAJOR
Removed a last constructor argumentPATCH
Changed format of the returned method resultMAJOR
New method exception (excluding subtypes of existing exceptions)MAJOR
New method exception (subtypes of an existing one)PATCH
JavaScript Class (marked with @api)New classMINOR
New method addedMINOR
New argument addedMINOR
Class removedMAJOR
Method removedMAJOR
Argument removedMAJOR
New eventMINOR
Renamed eventMAJOR
Removed eventMAJOR
New event propertyMINOR
Changed event propertyMAJOR
Removed event propertyMAJOR
Changed event orderingMAJOR
JavaScript Modules (AMD Modules) (marked with @api)New moduleMINOR
New method addedMINOR
New argument addedMINOR
Module removedMAJOR
Method removedMAJOR
Argument removedMAJOR
New eventMINOR
Renamed eventMAJOR
Removed eventMAJOR
New event propertyMINOR
Changed event propertyMAJOR
Removed event propertyMAJOR
Changed event orderingMAJOR
Virtual Type (marked with @api)Virtual type removedMAJOR
Virtual type addedMINOR
URL Paths (Store-Front and Admin, GET)Path removedMAJOR
Removed/renamed a request parameterMAJOR
New required request parameterMAJOR
New optional request parameterMINOR
Console commands and their argumentsCommand removedMAJOR
New required argumentMAJOR
New optional argumentMINOR
Removed/renamed argumentMAJOR
New command exit codeMINOR
New commandMINOR
Less variables and mixinsRemoved variableMAJOR
Removed mixinMAJOR
New required mixin argumentMAJOR
Message queue topics and data typesTopic removedMAJOR
Topic arguments modifiedMAJOR
Consumer removedMINOR
New topic publishedMINOR
Layout handles declared by modulesNew layout page handleMINOR
New container/block added to handleMINOR
Removed/renamed container/blockMAJOR
Removed layout handleMAJOR
Static and dynamic events triggered by a componentEvent argument removedMAJOR
Event removedMAJOR
Schema of configuration types introduced by moduleSchema file or configuration type renamed/removedMAJOR
Obligatory node/attribute addedMAJOR
Node/attribute removedMAJOR
New optional node/attribute addedMINOR
Structure of System Configuration fields used by moduleConfig path addedMINOR
Config path removed/renamedMAJOR
Database structureTable removedMAJOR
Table addedMINOR
Column removedMAJOR
Column addedMINOR
Compatible changes in column configuration (soften column constraints: increase size, make optional)PATCH
Incompatible changes in column configurationMAJOR
Primary key column added/removedMAJOR
Added column to unique keyMAJOR
Removed column from unique keyMAJOR
Unique key added/removedMAJOR
Index added/changedPATCH
Foreign key addedMAJOR
Temporary tables added/removed/changedPATCH
Static view files (marked with @api)JS/CSS/LESS file removed/movedMAJOR
JS/CSS/LESS file addedPATCH

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:

Was this helpful?
  • Privacy
  • Terms of Use
  • Do not sell my personal information
  • AdChoices
Copyright © 2022 Adobe. All rights reserved.