Semantic Versioning- Major vs. Minor vs. Patch Release

Edit on GitHub

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 article 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”?

A release is a major when we make a change in the external API of a module. This includes changes to the internal contract. E.g., even when there is no change of a facade-method, there can be a change in the behavior so that the contract (~ expected behavior) changed. 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 4 hours for clients who did not extend the module. This typically happens when data needs to be migrated. In case of a Maxi Major, 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 4 hours for clients who did not extend the module.

What is a “Minor release”?

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

Our customers will get all new minor releases automatically during composer update if they use the ^ symbol in composer.json (e.g. "spryker/category": "^4.1.2"). We recommend to use the ~ symbol (e.g. "spryker/category": "~4.1.0") for all modules that have been extended at the project level to make sure that nothing breaks after a release. See Using ~ Composer Constraint for Customized Modules on how you can easily detect ^ in the extended modules and update them with ~.

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.

It is very important to understand that patch release and bug fix are not the same. A bug fix can be released as Major, Minor or Patch-Release, depending on the compatibility level. A Patch-Release can also ship an improvement of a feature (e.g., a performance increase).

Taking updates

Usually, you need to run composer update to get Spryker Core updates, as 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 could be considered as Minor or Patch release.

Some minor updates require specific development effort for the project, which is caused by deprecation of some old approach or 3rd party modules. It’s advised to check out the release notes published after the project’s start. Also, check out General Troubleshooting for solutions of general technical issues you might have.