Atomic Releases

Spryker Commerce OS Release Process

Spryker Commerce OS comprises more than 100 modules that offer a large collection of functionality.

Our Demoshop is project archetype that demonstrates how the modules are integrated.

But what happens if you don’t need all the modules?

The problem with many systems is that they force you to download the entire package together with its dependencies, even if you don’t need everything. When you update to a newer version you are forced to update components you don’t need.

Let’s say you don’t need to use in your project our CMS module because you want to integrate your own solution for content management. Will you need to download also the source code of the modules that you don’t need? Do you have to get updates also for the components that you don’t use?

The answer is no.

Spryker Commerce OS offers you great flexibility through its release process.

Each module has its own repository. You are free to choose which modules you want to use from our Operating System. In the root of each module you’ll find a composer.json file that contains the dependencies for that module. There is no need to actively track dependencies as they are automatically loaded.

We use semantic versioning in our release project, so you can easily configure what kind of updates you want to receive from us. This helps you avoid the support the stability to your project even during updates.

Git Subtree Split

We are using the subtree split functionality from Git so that we have separated repositories for each component. These separated repositories are updated once a new release is made for that component.

Every module contains a composer.json that defines the required dependencies and their version according to the module’s version. Below you can see an example of a composer.json file from one of our components:

  "name": "spryker/price",
  "autoload": {
    "psr-0": {
      "Spryker": "src/",
      "Acceptance": "tests/",
      "Functional": "tests/",
      "Integration": "tests/",
      "Unit": "tests/",
      "YvesUnit": "tests/"
  "require": {
    "spryker/application": "^2.0.0",
    "spryker/installer": "^2.0.0",
    "spryker/kernel": "^2.0.0",
    "spryker/library": "^2.0.0",
    "spryker/messenger": "^2.0.0",
    "spryker/product": "^2.0.0",
    "spryker/touch": "^2.0.0",
    "spryker/twig": "^2.0.0",
    "spryker/config": "^2.0.0",
    "spryker/silex": "^2.0.0"
  "description": "price bundle",
  "license": "proprietary",
  "minimum-stability": "dev",
  "prefer-stable": true,
  "extra": {
    "branch-alias": {
      "dev-master": "2.0.x-dev"

In the project level's composer.json file you can specify the components that you want to use along with their versions.

More about versioning see, Versioning.

Why use a subtree split?


  • avoid the update stress
  • freedom to update specific modules

Spryker Commerce OS development team:

  • develop as we used to

Release Process

  • easy to plan
  • easy to maintain
  • easy to deploy


Spryker Commerce OS uses semantic versioning in order to solve module dependencies. Semantic versioning allows you to predict if after an upgrade to a new version your project it’s still going to work as expected.

By using this notation for the released versions, we don’t force you to upgrade to a new version that would cause your application to break and as a consequence, effort in tackling the possible issues that might appear.

You can choose to get updates that include only bugfixes or new features. This flexibility on choosing the updates you’ll receive brings stability to your project.

Module versioning is composed of three numbers: {BC Break}.{Feature}.{Patch}.

Given this version notation, by incrementing the:

  • {BC Break} - the new version contains incompatible API changes
  • {Feature} - the new version contains new feature that does not break the backwards compatibility
  • {Patch} - the new version contains backwards compatible bug fixes.

You can read more about semantic versioning here .

We defined all internal APIs here.

Solving Dependencies

A dependency can change without breaking backwards compatibility. You want to be able to get these updates, since these updates can include bugfixes or new features. This can be easily achieved through the way you configure your dependencies.

Caret vs Tilde

To upgrade the dependencies in your project, you can use the significant release operators: tilde(~) and caret(^).

Caret(^) operator is recommended to be used for internal dependencies.

By using ^ you always allow non-breaking updates( the first number of the version will not change).

Version Compatible Versions


>=1.0.0 <2.0.0


>=1.2.0 <2.0.0


>=1.2.3 <2.0.0

Tilde(~) operator is recommended to be used for external dependencies (allows upgrading to versions that contain bug fixes only).

By using ~ you specify the minimum version you want to use, but you allow the last specified digit to go up.

Version Compatible Versions


>=1.0.0 <2.0.0


>=1.2.0 <2.0.0


>=0.2.0 <0.3.0


>=1.2.3 <2.0.0

Checking for newer versions

You can easily keep track of new module versions using composer-versions-check as add-on for your local composer tool. It will warn you about outdated Spryker Commerce OS module dependencies.


To install the composer version checker inside your VM:

composer global require sllh/composer-versions-check

After a composer update run, it could then output the following warning to help keep track of upgrades:

{count} packages are not up to date:

- spryker/{bundle-name} (2.0.2) latest is 3.0.0

That means you are currently running version 2.0.2 of this module and that a new major version 3.0.0 is available.

We recommend atomic upgrades in small module packages on a regular basis. This keeps the upgrading efforts at a minimum and makes each upgrade scope easily manageable. Small and regular updates then prevent errors that could happen from too large changes at once.

Additionally, by doing so you will always benefit from the latest improvements right away.

Make sure every minor or patch release is applied before upgrading to a major released version.

Do not perform any major upgrades without executing this command first:

composer update "spryker/*"

To speed up the composer update process, use this composer tool. After running composer global require hirak/prestissimo the next composer update or composer install command should be way faster for both local development and server deployment.

Now you can test first that everything is working as expected and only then start a major upgrade.

Composer Update
Execute this command at least weekly to assert you have the latest fixes.