Introduction

This document describes ICM versioning approach in the context of release compatibility.

ICM 11+

Product Version (3 Digits)

ICM 11+ versioning follows the compatibility aspect only. The transition from ICM 11 to ICM 12 is similar to upgrading from a larger patch step of ICM7.10.

ICM uses semantic versioning (v2). For more information, refer to https://semver.org.

1. Major - contains breaking changes - Going forward to this release can break a customization (it does not matter how high the probability is).

2. Minor - contains additional functionality - Going forward to this release should not break a customization. Going back from this release can break the customization.

3. Patch - contains fixed functionality - Going forward and backward to this release should not break a customization.

4. Suffix - optional part of the version number to provide additional information for usage (like -LTS).

ICM 11 Customization

ICM 11 introduces a new customization concept. Each release of a customization has its own version number. It is not necessary to create releases for customization for each ICM release anymore. But it is recommended to test customization at least for each minor release. The ICM 11 releases page provides an overview of ICM and customization release numbers. Standard customization also follows semantic versioning.

ICM 7.10

Up to ICM 7.10, new product versions were determined by marketing, product increment (effort), and compatibility considerations. ICM 7.10 has evolved from a standard GA release to a generation of ICM versions.

ICM 7.10 - Product Version (4 Digits)

A product version of Intershop Commerce Management has 4 digits, e.g. 7.6.3.14.
The four positions have the following meaning:

1. Generation (e.g. 7) – New product generation (marketing driven)

2. GA (e.g. 6) – Public release with new functionality

   1. Deprecation is allowed (two minor versions minimum)

   2. APIs can be broken, but must be documented

3. Patch (e.g. 3) – May contain bug fixes or new features

   1. Product Acceptance- and Performance Tests are performed

   2. (Exceptions minor updates must be approved by product steering)

   3. Minor updates of third party libraries

   4. APIs can be broken, but must be documented

4. Hotfix (e.g. 14) – Bug fixes or features shipped to the customer as soon as possible

   1. Contains all previous hotfixes

   2. Only non-API breaking features can be released

   3. No minor updates are allowed

   4. Patch updates of third party libraries

The product is technically defined by a version of an assembly. The product version number is the version number of the assembly (Intershop7). This assembly contains dependency declarations (including versions) of components. These components can follow their own version schema.

ICM 7.10 - Mapping Product and Component Version for Continuous Releases

The following table shows the relation between component version and product version.

For example, a new major version of a component (e.g., f_business) results in a new patch version of the product.

ICM 7.10 - Component/Cartridge Version

Components are bundled in component sets, similar to multi-projects.

Component sets follow their own life cycle, starting with version 1.0.0. In the binary repository, these sets have their own group, for example:

• com.intershop.platform:core:1.0.0

Example: com.intershop.platform:bc_service:10.0.4

Major – Incompatible Changes Included

Goal:

• Remove deprecated methods, classes

• Rework features

• Introduce new features with database changes

You can:

• Introduce any changes

Example:

• 10.0.4

Minor – Compatible Changes Included

Goal:

• Add new functionality without breaking the existing customization

• Backward compatible (existing implementations are still working)

• Deployment can do rolling update (means older versions may run in parallel)

• Migration of customization is mostly not necessary (only in edge cases), e.g.:

  • Test cases require new mocks (used via DI)

  • Existing private/protected methods, members could reduce the visibility of new introduced methods/members

You can:

• Patch and minor level updates of libraries (or underlying component sets)

• Add new dependencies

• Add APIs

• Deprecate APIs

You cannot:

• Remove API

• Add abstract methods (e.g., interfaces)

• Introduce DBMigrate

Example:

• 10.0.4

Patch – Bug Fixes Only (Compatible for Usage and Implementation)

Goal:

• Implementations will work against all patches of a minor version

• Customization layer can jump forward or backward without problems

• No migration of customization necessary

• Deployment can do rolling update (means older versions may run in parallel)

You can:

• Fix behavior

• Add documentation for API

• Patch level updates of libraries (or underlying component sets)

• Add classes or interfaces to "internal" packages

• Deprecate classes or interfaces in "internal" packages

You cannot:

• Touch APIs (except documentation)

• Add or remove parts of API

• Deprecate APIs

• Introduce DBMigration

• Add injection of members

You should not:

• Remove internal classes or interfaces (may be used in projects)

Example:

• 10.0.4

Version Extension - Post Release Fixes

Goal:

• Provide fixes with minimal code impact to the patch, in case the following patch was released before

You can:

• Fix behavior

• Add documentation regarding the fixed behavior

Example:

• 10.0.4-SP1

Artifact Based Versioning

REST API

REST API is independent of component versioning. REST API uses semantic versioning when the REST API definition (extractable from OpenAPI definition) has been modified.

• MAJOR - API breaks (e.g. removed resources)

• MINOR - new resource

• PATCH - documentation changes (optional)

Independent Components

Completely independent components can be implemented in a single project build. These components are collected in a special group named "com.intershop.common", e.g.:

• com.intershop.common:encryption:1.1.0

A component set can define an API as well. This is a common approach if there is no default implementation, see javax.inject:javax.inject:1 at http://mvnrepository.com/artifact/javax.inject/javax.inject/1. This approach is used for "Service API", so modification of this type of API can be separated.

Managed Services Versioning

Managed service interfaces are located in components. The API of a component contains such interfaces. Therefore, the component version declares major, minor changes of that API too.

f_api is a separate API component set. This component set can contain multiple service interfaces. The product can also support multiple versions of an API.

So, the package contains the major version number of that package too. This component set con contain, for example:

• com.intershop.api.data.common.v1

• com.intershop.api.data.common.v2

• com.intershop.api.service.payment.v1

• com.intershop.api.service.taxation.v2

Under some circumstances, service interfaces are marked with a @BETA annotation. This means, this interface is marked as possibly unstable. Incompatible changes to such interfaces must be marked with a new MAJOR version of the component set (semantic version), but it is not necessary to create a new package with the new major version.

Version Number Extensions