API Stability
=============

Shopware ERP ships in source form, which means that it is possible to read and understand all code that makes up the
plugin and, in theory, interface with it. However, using this approach is not recommended since the stability guarantees
of the Shopware ERP PHP API do not cover the entire plugin code.

Releases of Shopware ERP follow `Semantic Versioning <https://semver.org/>`_ guidelines. In short, this means that
breaking changes will only happen as part of major releases, that is when the ``x`` part of an ``x.y.z`` version number
changes. However, it is possible for behavior to change in a breaking way as part of minor or patch releases if the
former behavior was incorrect in the sense of being a bug.

The stability guarantees made according to the semantic versioning framework cover:

- the database schema,
- the PHP model classes, and
- the service classes in ``Components/`` and all classes which are part of their interface

The following types of changes are considered breaking and will only happen as part of a major release for the
aforementioned parts of the plugin:

* removing or renaming database tables or columns,
* adding required columns without a default value to an existing database table,
* removing or renaming classes or their public and protected methods,
* adding required parameters to existing public and protected methods, and
* adding abstract methods to classes or interfaces, with the exception of service interfaces (see
  :ref:`using-decoration` for an explanation on why this is and how to get around this)

Please note that for all PHP classes outside the scope of the public API (which includes Commands, Controllers and
Subscribers), any of these breaking changes may happen as part of minor and patch releases.
