Versioning policy

Versioning policy overview

The Magento system and its components use the software (or 鈥減latform鈥�) version to indicate the compatibility of changes in the implementation (on the code level). By comparing two versions of the same component, one can tell whether it has any backwards-incompatible changes in the public API or other significant code changes.

Magento software versioning complies with the following specifications:

Version formats

Stable release versions 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 pre-release version format is: MAJOR.MINOR.PATCH-<alpha | beta | rc>n, where alpha, beta or rc are stability indications, as described in the version_compare() specification, and n is an increment number to distinguish releases of the non-stable versions.

Public APIs

Source code is considered public API only if it is explicitly marked as such using the @api docblock tag. This designation indicates the code can be used or customized by other components, such as formal interfaces and dependency injection points.

For PHP code, compatibility of @api may be tracked on the level of structural elements (class signatures, interfaces, methods, etc.). For other source code, compatibility is tracked only on file level (for example, the file has been deleted or renamed).

Where versioning is used

The software version can be found in the source code of any Magento component or bundle, inside the composer.json file.

It can be declared as the version of the component:

"name": "acme/foo",
"version": 1.2.0

Or it can be used to declare a dependency on a particular version of a component:

"require": {
    "acme/foo": "1.2.*",
    "acme/bar": "2.2.0"
}

Release types

This section describes how exactly and when the software version numbers will be changed with releases.

The software version will always change with any release of Magento source code.

Development releases

In every development release (鈥減re-release鈥� version), the same value of version number will be propagated in all Magento components and their dependencies.

Magento may update the x.y.z version in way perscribed by Semantic Versioning, but also could release the same x.y.z with different stability and/or index numbers, For example, 0.1.0-alpha1 -> 0.1.0-alpha2, 0.1.0-alpha3 or 2.0.0-alpha3 -> 2.1.0-beta1 -> 2.1.0-beta2

	Previous Release	Next Release
Component Version	"name": "magento/foo", "version": 0.1.0-alpha87	"name": "magento/foo", "version": 0.1.0-alpha88
Dependency in Other Components	"require": { "magento/foo": "0.1.0-alpha87" }	"require": { "magento/foo": "0.1.0-alpha88" }

Stable releases

In every stable release, the same value of version number will be propagated in all components, but dependencies will have a wildcard (*) pattern.

The x.y.z numbers will change according to Semantic Versioning policy provisions. For example, 1.0.0 -> 1.0.1 -> 1.1.0 -> 1.5.0 -> 1.5.1 -> 2.0.0 -> 2.1.0. Also, Magento may decide to change the 鈥渕inor鈥� version instead of the 鈥減atch鈥� version.

	Previous Release	Next Release
Component Version	"name": "magento/foo", "version": ~1.2 This is equivalent to >= 1.2 < 2.0.0.	"name": "magento/foo", "version": 1.3.0
Dependency in Other Components	"require": { "magento/foo": "1.2.*" }	"require": { "magento/foo": "1.3.*" }

Previous Release

Next Release

Component Version

"name": "magento/foo",
"version": ~1.2

This is equivalent to >= 1.2 < 2.0.0.

"name": "magento/foo",
"version": 1.3.0

Dependency in Other Components

"require": {
    "magento/foo": "1.2.*"
}

"require": {
    "magento/foo": "1.3.*"
}

Example lifecycle

The following steps demonstrate the packaging and backward compatibility story from the view of Magento, system integrators, and extension developers. This example uses several composer packages on the public github to simulate a merchant site, 2 core Magento modules, and a third-party extension.

Start by cloning the master branch from github. This sample in composer.json states this site is dependent on a release candidate of a simulated Magento 2.0 release.

{
  "name": "myexamplestore/sample-site",
  "description": "A sample site",
  "type": "project",
  "version": "1.0.0",
  "require": {
    "myexamplestore/product-bundle": "2.0.0-RC1"
    }
}

Run the composer update command. Core modules a & b are pulled down from the repository.

Now the SI includes a third-party extension by adding the composer dependency. This extension trusts our BC and sets the appropriate version on the module-a core dependency.

{
  "name": "myexamplestore/sample-site",
  "description": "A sample site",
  "type": "project",
  "version": "1.0.0",
  "require": {
    "myexamplestore/product-bundle": "2.0.0-RC1",
    "myexamplestore/acme-extension": "~1.0"
    }
}

Run composer update and see the new extension downloaded.

When Magento releases 2.0 GA, the SI updates the site composer.json to the release version.

{
  "name": "myexamplestore/sample-site",
  "description": "A sample site",
  "type": "project",
  "version": "1.0.0",
  "require": {
    "myexamplestore/product-bundle": "2.0.0",
    "myexamplestore/acme-extension": "~1.0"
    }
}

Run composer update and notice the core modules were updated since RC1, but the extension remains unchanged because of BC policy. This step repeats with each subsequent release of Magento (2.1, 2.2, 2.3, etc.). Deprecation strategy and community communication happens in 2.3.

Magento decides backward incompatible changes are allowed and does this as part of the upcoming release 2.4.

{
  "name": "myexamplestore/sample-site",
  "description": "A sample site",
  "type": "project",
  "version": "1.0.0",
  "require": {
    "myexamplestore/product-bundle": "2.4.0-RC1",
    "myexamplestore/acme-extension": "~1.0"
    }
}

Run composer update and notice that acme-extension is marked as incompatible.

Based upon previous communication, the developer has updated the extension so the SI updates to the new extension version.

{
  "name": "myexamplestore/sample-site",
  "description": "A sample site",
  "type": "project",
  "version": "1.0.0",
  "require": {
    "myexamplestore/product-bundle": "2.4.0-RC1",
    "myexamplestore/acme-extension": "~2.0"
    }
}

Run composer update. Updates to core modules are returned as third-party extensions.

Versioning policy