Support Policy
This page describes the different aspects of the support policy between commercetools and consumers of the Custom Applications features.
Beta
Beta features are indicated with the BETA flag. The flag can be visible in the main navigation of the documentation website as well as at the top of a page. The latter is a link to this page.
A feature is marked as Beta when is stable enough to be used in production but may not yet be fully feature complete. Although expected to be stable, any Beta feature can be subject to change and should be used carefully in production. During the Beta period commercetools is still in the process of gathering the necessary feedback from consumers to complete and finalize the features. After the Beta period, the feature is promoted to General Availability and announced in the release notes.
Make sure to read and understand the Minimum required maintenance policy before starting to use Custom Applications in production, including the Deprecation notice and End Of Life (EOL).".
Release process
Tooling and packages related to Custom Applications are released and published to Node Package Manager (NPM) following Semantic Versioning (SemVer).
Releases are documented in both a CHANGELOG.md file and in the GitHub release pages in the following repositories:
- Changelog
- Release notes
All published packages to NPM are listed in the following scoped packages:
Release cadence
commercetools strives to improve tooling and packages around Custom Applications continuously. This means that we do not follow a strict release cycle but instead publish releases in meaningful intervals, potentially multiple times a week. Minor and patch versions are likely to be 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.
Stable releases and pre-releases
By default, all releases go to the next distribution tag and should be considered prereleases. This gives commercetools a chance to test a release internally before marking it stable in the latest distribution channel.
It is recommended to use packages only from the latest distribution channel. The next channel is stable enough to be used on production but it's not officially supported. It can be used to try out new features or to get important bug fixes.
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 a Custom Application:
- It affects a component or module not used within the Custom Application
- It affects a component or module used within the Custom Application
- 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 "old" Node.js version, thus releasing a major version. As a consequence, commercetools could release a new major version as well for dropping support to a specific Node.js version. However, this unlikely affects consumers of Custom Application packages.
- React releases some new feature that requires a specific minimal version of React. Therefore, commercetools could release a new major version that requires Custom Applications to run to a minimal React version.
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 Custom Application's code.
Minimum required maintenance policy
All the official Merchant Center applications are constantly kept up-to-date with the released tools and packages. This ensures that all the latest bug fixes and features are consistently adopted by all applications.
In regards to Custom Applications, commercetools does not expect the same amount of maintenance as it requires internally. However, commercetools recommends that Custom Applications are updated at regular periods and maintained in planned intervals, to avoid falling too many versions behind. Not doing so might result in an increased maintenance effort in case the codebase needs to be updated to multiple versions, even more so for major versions and/or deprecated API functionalities.
| Feature maturity | Recommended update interval |
|---|---|
| Beta | At least once a quarter (every 3 months) |
| General Availability | At least twice a year (every 6 months) |
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.
Deprecation notice and End Of Life (EOL)
Some packages, for example @commercetools-frontend/application-shell, interact with different commercetools HTTP APIs. Changes to those packages might include updates related to HTTP API functionalities, usually in a backwards compatible way.
However, it can happen that some HTTP API functionalities might be deprecated over time and eventually removed.
The application kit packages rely on internal Merchant Center HTTP APIs that are not covered by the standard commercetools HTTP API policy of no breaking changes. For Custom Applications this means that, in case the application is not kept up-to-date within the supported deprecation period, it might stop working because of the removed HTTP API functionalities.
In case some HTTP API functionalities need to be deprecated, commercetools starts a deprecation process as following:
- The HTTP API feature is marked as deprecated (for example GraphQL fields get the
@deprecateddirective) - The deprecated feature is removed from the packages that refer and use that feature
- A new breaking change version of the packages is released, marking the starting point for how long the feature will remain deprecated
- The deprecation period (start to end) is documented on this page
- During the deprecation period, commercetools tracks the usage of the deprecated features, to determine if there are still applications using them
- Towards the end of the deprecation period, commercetools might contact the owners/maintainers of applications that are still using versions prior to the deprecation release
- After the deprecation period ends, commercetools is free to remove the deprecated functionalities from the respective HTTP APIs.
| Feature maturity | Deprecation period |
|---|---|
| Beta | 4 months |
| General Availability | 12 months |
Be aware that commercetools does not take any responsibility towards applications that might stop working after the deprecation period, because of the removed features.
The following table lists all the released versions affected by the deprecation period:
| Version | Start date | End date |
|---|---|---|
v5.0.0 | 2019-01-03 | 2019-05-03 |
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, Dependabot, Greenkeeer.
Those tools and services can be configured to meet everyone's needs, for example to get updates only once a week.
Hosting
Customers using Custom Applications are responsible for the maintenance of their Custom Applications. This includes hosting and deployments. commercetools does not take any responsibility towards incidents and service disruptions related to Custom Applications caused by their underlying infrastructure.
Issues and support requests
For any question or issue about Custom Applications, we recommend to open a GitHub Issue in one of the repositories (according to what the issue is about). Any sensitive information should be left out, as Issues are publicly visible.
In case the issue must contain sensitive information, for example the name of a customer project, open a commercetools support ticket.
Never ever include password, credentials, or any private information in any issue (public or private)!
Contributing
All packages and tools provided by commercetools are open source and licensed under MIT. At commercetools we love open source and we do what we can to contribute to other open source software that we also use internally. As such, we are happy to receive any contributions about our own packages, that being an Issue or a Pull Request.