Documentation

Maintenance guidelines

Learn about general support and maintenance recommendations for customizations

Release process

Tooling and packages related to a customization are released and published to Node Package Manager (NPM) following Semantic Versioning (SemVer).

Releases are documented in each package's CHANGELOG.md file and in the GitHub release pages in the following repositories:

All published packages to NPM are listed in the following scoped packages:

Release cadence

commercetools strives to continuously improve the tooling and packages around customizations. We do not follow a strict release cycle. Instead, we publish releases in meaningful intervals, potentially multiple times a week. Minor and patch versions are likely released more frequently than major versions.

According to Semantic Versioning, minor, and patch version releases can be safely updated and do not require any additional maintenance work. However, a major release indicates a breaking change (see Breaking changes) and might require maintenance work. Breaking changes are kept to an absolute minimum and are planned ahead of time.

Breaking changes

Breaking changes are introduced whenever there is a major version release, for example from v1 to v2.

How a breaking change can impact your customization:

  1. It affects a component or module not used within the customization
  2. It affects a component or module used within the customization
  3. It affects a component or module directly interacting with some of commercetools's internal APIs

A new major release does not always mean that breaking changes directly affect consumers of the packages. Some examples are:

  • A dependency package drops support for an older Node.js version, thus releasing a major version. As a result, commercetools could subsequently release a new major version to also drop support for the Node.js version. However, this is unlikely to affect consumers of Custom Application or Custom View packages.
  • React releases a new feature that requires a specific minimum version. As a result, commercetools could subsequently release a new major version, updating the minimum React version requirement for Custom Applications or Custom Views.

All breaking changes are thoroughly documented in the release notes together with migration steps to facilitate the version update. This also helps to identify if changes are needed within the customization.

Minimum required maintenance policy

All built-in Merchant Center applications are kept up-to-date with the released tools and packages. This ensures the uniform adoption of the latest bug fixes and features across all applications.

In regards to Custom Applications and Custom Views, commercetools does not expect the same amount of maintenance as it requires internally. However, commercetools recommends that customizations are updated at regular periods and maintained in planned intervals, to avoid falling too many versions behind. Failure to do so may lead to increased maintenance efforts if the codebase requires updates across multiple versions, especially for major releases and/or deprecated API functionalities.

It is important to keep the dependencies up-to-date, especially to get the latest bug fixes and security patches. See also Automate maintenance of dependencies.

Automate maintenance of dependencies

To help with the maintenance of dependencies, there are tools and services that can be used to automatically get dependency version updates to your own repository, for example, Renovate, or Dependabot.

Those tools and services can be configured to meet a wide range of needs, for example, to get updates only once a week.

Hosting

Customers using Custom Applications or Custom Views are responsible for the maintenance, hosting, and deployment of the customization(s). commercetools does not take any responsibility for incidents and/or service disruptions related to customizations which are caused by their underlying infrastructure.

Issues and support requests

If you encounter issues developing a Custom Application or Custom View, we recommend opening a GitHub Issue in one of the following repositories, depending on the issue:

If you have questions or need help, we recommend opening a GitHub Discussion in one of the following repositories, depending on the issue:

Never include passwords, credentials, or any private or sensitive information in a Github Issue since they are publicly viewable.

If the issue must contain sensitive information, for example, the name of a customer Project, open a commercetools support ticket.

Contributing

commercetools provides all packages and tools under the open-source MIT license.

At commercetools, we love open source and actively contribute to other open source software that we also use internally. As such, we welcome contributions to our packages, whether in the form of an issue or a pull request.

You can read more about the contribution guidelines in the following repositories: