Semantic versioning - major vs. minor vs. patch release

The Spryker Commerce OS versioning of modules relies on the semantic versioning approach, which implies a clear set of rules and requirements that dictate how version numbers are assigned and incremented. This document describes how we release modules and version them depending on the release type.

What is a release?

A pull request can ship a new feature, bug fixes, and improvements to existing features. A pull request contains one or multiple modules. Each module can be a major, minor, or patch release.

What is a Major release?

When we make a change to the external API of a module, it is a major release. This includes changes to the internal contract. Even when there is no change in a facade method, there can be a change in the behavior so that the contract (~ expected behavior) changes. Please obey the constraints for major releases.

Our customers need to change their composer.json file to get major versions of modules.

We have two types of major releases:

• A maxi-major. When the release effort is higher than four hours for clients who did not extend the module. This typically happens when data needs to be migrated. In case of a maxi-major release, the previous version automatically gets all bug fixes and security patches (LTS) as long as anyone uses this version.
• A mini-major. When the release effort is lower than four hours for clients who did not extend the module.

What is a Minor release?

A release is minor when the internal API is changed. For example, when the signature of internal models or constructors is changed, or classes are renamed. Actually, it is anything that can break extensions using inheritance or composition on a project level.

Our customers get all new minor releases automatically during composer update if they use the ^ (caret) symbol in composer.json—for example, "spryker/category": "^4.1.2". We recommend using the ~ (tilde) symbol for all modules that have been extended at the project level to make sure that nothing breaks after a release—for example, "spryker/category": "~4.1.0". For mode details about how you can easily detect ^ in the extended modules and update them with ~, see Using ~ Composer Constraint for Customized Modules

What is a Patch release?

A release is a patch when the internal API of a module is not changed. So all internal method signatures are unaffected, and there is no change in the call flow or behavior of any method.

Taking updates

Usually, you need to run composer update to get Spryker Core updates, because by default the modules are constrained with ^. After each update, you need to run console transfer:generate to update DTOs. Adding a field to DTO is BC change and can be considered as a minor or patch release.