Backward compatibility policy
This page is for engineers who change Exponential or an extension, and for those who plan upgrades and need to know what may break. It summarizes Compatibility, releases and deployment.
Contents
What counts as a break
A change breaks compatibility when an installation or extension that worked before needs an action to keep working, or behaves differently without being asked to:
| Kind | Examples |
|---|---|
| Settings | a setting removed or renamed, its meaning or default changed, a section moved to another file |
| Templates | a template removed or moved, a variable no longer passed, an override Source path changed |
| PHP API | a public class, method or function removed or renamed, a signature or return type changed |
| Database | a table or column added, removed or changed (an upgrade needs SQL) |
| Command line | a command, option, output format or exit code changed |
| Behavior | a default changed (security headers, cookies, access checks), a permission now required |
| Files | a file that sites copy or include changed in form |
The rules
- Every break has upgrade notes in
doc/eng-us/bc/<series>/, opening with the In short table (Changelogs and upgrade notes). - New behavior is opt-in; bug fixes need not be. A feature arrives switched off or with a default that keeps the old result.
- New settings have a safe default in the shipped file, a comment, a feature page section and a changelog line.
- Identifiers are not renamed.
eZ*andezp*classes, tables, settings and paths stay; the product rename changed only text (The product is called Exponential). - Moved code keeps its entry point. When views, scripts and cronjob parts became classes in 6.0.15, every file kept its path as a one-line call.
Deprecation
- A replaced API stays available and is marked
@deprecatedwith its replacement; some write a strict-mode notice througheZDebug::writeStrict()when used. - A renamed command keeps its old name as a deprecated alias that still works (Platform package forks and command renames).
- A removal is announced in the changelog's Removed section and in an upgrade note.
- Deprecated APIs inherited from the old code base have no removal date; none is announced for the 6.0 line.
Known exceptions
- Security defaults changed without opt-in in September and October 2026: security headers,
HttpOnlyandSameSitesession cookies, a stricter upload check, new access requirements for some remote services. Security fixes are treated like bug fixes: on by default, documented with how to undo them deliberately. - Accounts without an
ezuser_settingrow cannot sign in since August 2026, and override blocks followPrioritysince July 2026 (Behaviour changes of July and August 2026).
For the upgrading side
- Read the checklist of every period you pass, in order.
- Search your extensions for overridden kernel classes and copied kernel templates: they do not get fixes and can break silently.
./console exp:checkclassesreports classes PHP refuses to load; the upgrade check compares files and tables with the release.- Test with your own content and your own extensions before the production upgrade (Deploying a change).
Related pages
- Upgrading
- The upgrade checklist for extensions
- Release and upgrade planning
- Free documentation: this page is free to copy, translate and improve under the GNU FDL 1.3.
Become an Exponential Partner
Partners share their information, provide funding, contribute back and develop the products with us, and that is how Exponential grows. A partner website and dashboard are planned for mid-2027: please become a partner today to speed up our growth rate and land new features faster.