Skip to content

Latest commit

 

History

History
245 lines (189 loc) · 7.69 KB

versioning.md

File metadata and controls

245 lines (189 loc) · 7.69 KB
layout group subgroup title menu_title menu_order version github_link redirect_from
default
arch-guide
Architectural Basics
Versioning policy
Versioning policy
4
2.0
architecture/versioning.md
/guides/v1.0/architecture/versioning.html

Overview {#verpol}

The Magento system and its components use the software (or "platform") 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 backward-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:

{% highlight JSON %} "name": "acme/foo", "version": 1.2.0 {% endhighlight %}

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

{% highlight JSON %} "require": { "acme/foo": "1.2.*", "acme/bar": "2.2.0" } {% endhighlight %}

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 ("pre-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 "minor" version instead of the "patch" 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.*"
}

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.

  1. 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.

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

  2. Run the composer update command. Core modules a & b are pulled down from the repository.
  3. 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.

    {% highlight JSON %} { "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" } } {% endhighlight %}

  4. Run composer update and see the new extension downloaded.
  5. When Magento releases 2.0 GA, the SI updates the site composer.json to the release version.

    {% highlight JSON %}{ "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" } } {% endhighlight %}

  6. 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.

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

    {% highlight JSON %} { "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" } } {% endhighlight %}

  8. Run composer update and notice that acme-extension is marked as incompatible.
  9. Based upon previous communication, the developer has updated the extension so the SI updates to the new extension version.

    {% highlight JSON %} { "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" } } {% endhighlight %}

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

Related topics

Backward compatibility

Architectural basics