_Many users of eZ software expect that eZ is a reliable company with stable products they can build upon, they are large enterprise customers that build complex applications on top of eZ software. With more frequent major releases several of these customers have expressed concerns about having to change their implementation often, e.g. v5 to v1, and v1 to v2. This document is about eZ more clearly committing to what we have said in the past, and so far followed from v5 to v2; We have a BC policy that allows people to rely on eZ software for the long run.
eZ Platform, including all packages from eZ Systems AS are following "Semantic Versioning", aka SemVer.
However SemVer is only talking about API changes:
- It does not cover changes to implementation; improvements or even new features in the implementation.
- It also does not specify if a UI is to be considered under API rules or as an implementation.
- Or changes to features, including removal of features.
At eZ we consider any REST API as well as any interface (code contract) to be something that adhers to SemVer. We also aspire to follow the same rules for features on a product level, but we might sometimes for instance adjust and/or improve our featurs based on customer requests or issues in patch releases, all within SemVer API rules.
As we are now doing major releases more often then we did in the past, below you can find our extended BC promises which goes beyond SemVer rules for our Content Repository API's in order to provide a stable fundation for us all to build uppon.
It's worth noting that we continusly improve our code in minor releases (x.Y.z) within SemVer rules:
- Remove API and features deprecated in X.y, in any minor version of X+1.y, and not just X+1.0 as suggested as earliest removal per SemVer.
- On product level replace prevously communicated to be re-implemented features (packages) with a newer once, assuming public api usage is not broken and migration path is provided (if needed).
- As long as it does not break API or configuration, we might move a feature from one package to the next within our product. It will during move keep the same license, or move to a more permissive one (from closed to open), opposite direction needs to adhere to normal SemVer deprecation cycle.
!! Security considerations for minor / patch releases: Normally security issues only affect implementation, however in extreme cases where implementation details has leaked into API and is affected, or API (a method or endpoint) otherwise can not stay the same. We reserve the right to be able to correct mistakes, but keeping the affected API usage as limited as possible.
"Public API" in eZ context refers to code in */API/* namespaces or documented with @api,
as well as it's REST API (avaiable on /api/rest/v2 path), today covering our full set of Content
Repository features. This is covered by a BC promise beyond what is provided by
SemVer. The BC promise is across a major version for smaller
changes, and across several major versions in case of major changes.
Example:
For API features _(methods or smaller interfaces)_ deprecated in 6.x series, they can earliest be removed in v8.0.0. In
contrast, under Semantic Versioning it could have been removed in v7.0.0.
For major changes, as in deprecating the whole Respository API in 6.x series, may not be removed before earliest in
v9.0.0 assuming a yearly major release cycle, otherwise after minimum of two years have passed. This is however
not an option we are likly to ever use, our API's are designed to evolve over time to improve.
Exceptions:
- Major releases (X.y.z): Taking advantage of for instance improvements in PHP, like native type hinting. This does not need prior deprecation as long as type is same or similar (e.g. array vs iterable vs generics) as previously documented.
- As API has BC promise for consumption, official extension point (cusotm implementation) is via SPI layer, this means:
- Minor (Feature) releases (x.Y.z): Implementation the API interfaces is possible, however optional arguments or new methods might be added as long as it is possible to have implementation working across new and prior releases at the same time.
- Patch releases (x.y.Z): Extending the API implementation may break as implementation changes. Also smaller bug fixes or improvments to existing features (interface doc, doc or implementation) is to be expected, where for instance doc/spec and implementation has been inconsistent or wrong.
The point of this is to secure a stable foundation for everyone for all provided Public API's, while at the same time allowing eZ and the community to be able to maintan the code base for a long time in LTS releases.
As of 7.5LTS/8.0, SPI (Service Provider Interface), being the official way to extend the Repository, is following the same extended BC rules as Symfony Framework is following: http://symfony.com/doc/current/contributing/code/bc.html
Example:
If we need to add or change methods to SPI in patch or minor releases, we need to add new interfaces,
and in next major (if needed) deprecated the introduced interface and move over to main interface.
Also major release does not introduce new things, this is done in paralle released LTS release, while
deprecations are cleaned up in the major release (or subsequent minor releases of the major). Allowing
usage of non deprecated features to work across a given LTS and parallel major release.
This covers interfaces and classes in eZ\Publish\SPI\* namespace and other namespaces using the word *\SPI\*, not implementation classes found in eZ\Publish\Core\* or other namespaces.
NOTE: We are considering extending the longer BC promise of API also for SPI layer in the future, however for certain parts of the SPI (mainly Persistance) we are soon about to build a second implementation and want to make sure to have two implementations in place before we make it even harder for us to be able to fix potential mistakes in the interfaces for future major versions.