Introduction

The PWA versioning system follows semantic versioning principles to communicate the nature and scope of each release in a consistent and predictable way.

Due to the full availability of the PWA source code in GitHub, PATCH releases are usually not created, since new bug fixes can easily be consumed by any project via git cherry-pick from the develop branch or the pull request branch.
Publishing such changes within a PATCH release is not necessary, since projects need to integrate the changes as a merged commit either way.
There is no “just incrementing a dependency version” concept due to the Intershop PWA not being a library, but rather a blueprint to start a custom storefront project.

The Intershop PWA is not maintained in multiple versions with subsequent new MINOR or PATCH releases to parallel versions.
Rather, it follows a linear path of released versions that uses a MAJOR or MINOR release to signal the scope of contained changes.

Versioning Scheme

The Intershop PWA follows the versioning format MAJOR.MINOR.PATCH.

The version number primarily signals upgrade impact, not the functional type of change.
It reflects upgrade effort and scope.

Breaking Changes

A breaking change is defined as “a change in one part of a software system that potentially causes other components to fail“ (Wiktionary).

Projects upgrade by incorporating code changes from higher PWA versions into their source code.
They do not simply “consume” a newer PWA version by updating a version number.

Each project has its own customizations, ranging from minimal to extensive.
A project that uses the PWA without code-level customizations (for example, only updating CSS styles) can upgrade to any version, including major versions, without much adaptation effort.
In such cases, there are no breaking changes because nothing conflicts during migration.

The definition of a breaking change refers primarily to whether changes in the standard PWA code require project teams to manually adapt their customizations when upgrading (e.g., custom code no longer compiles or behaves correctly without adaptation).

The breaking changes listed below represent typical customization points where project-specific modifications are most likely to conflict with changes made in the standard PWA:

• Angular upgrade to a major version (systematic code changes across the codebase)
• Breaking changes in dependencies (e.g., Bootstrap)
• Removal of support for specific older REST API endpoints (e.g., the PWA uses a new version of an ICM REST API endpoint and removes the existing fallback to the older endpoint version).
• Feature removal or major feature rework
• Public signatures that require code adaptations
• Changes in the routing structure (route paths; e.g., SEO-critical: deep links, sitemaps, query parameter conventions)
• Required configuration, environment, or deployment changes (configuration keys, environment variable names, feature toggle identifiers)