Compatibility, releases and deployment
This page is for developers who change Exponential 6.0.x or an extension and for administrators who upgrade and deploy it. It answers three questions: what counts as a breaking change and what has to accompany one, how versions are numbered and released, and in which order a change is deployed so that no server keeps running old code. Each rule says must or should, how the repository implements it, and where it is not met yet.
Backward compatibility policy
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. In particular:
| 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 to a template, an override Source path changed |
| PHP API | a public class, method or function removed or renamed, a signature or return type changed, a class moved into a namespace without the old name |
| 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 where none was |
| Files | a file that sites copy or include (views, cronjob parts, scripts) changed in form |
The rules
- Every break must have upgrade notes in
doc/eng-us/bc/<series>/. The directory exists per series, fromdoc/eng-us/bc/4.1/todoc/eng-us/bc/6.0/(84 pages indoc/eng-us/bc/6.0/at the time of writing). A page opens with an In short table with the rows What changed, Who is affected, How to check and How to fix; examples: Commands, cronjob parts and module views as classes, exp:ini. Changes that span many areas are collected per period with a deploy order and a checklist table, for example Behaviour changes of 1 and 2 October 2026. - New behavior should be opt-in, bug fixes need not be. A new feature arrives switched off or with a default that keeps the old result; examples are the class-based views ("the old way still works", plain-file views keep running) and the Velocity engine options in Velocity engine upgrade notes ("Nothing changes by itself. New, opt-in: ...").
- New settings must have a safe default in the shipped
settings/<file>.ini, a comment there, a section on the feature page indoc/eng-us/features/6.0/and a line in the changelog. - Identifiers are not renamed. Existing
eZ*andezp*classes, tables, settings and paths stay (see Layering and naming rules); the 2026 product rename changed only text (The product is called Exponential). - Moved code keeps its entry point. When the code of a script, view or cronjob part moved into a class in 6.0.15,
every file kept its path and became a one-line call, so includes, cron entries and
--helpoutput did not change.
Deprecation
- A replaced API stays available and is marked
@deprecatedwith the replacement (54@deprecatedtags inkernel/andlib/, for exampleeZContentObject::contentObjectListRelatingThis(), replaced byreverseRelatedObjectList(), andeZUser::isLoggedIn(), which still works and writes a strict-mode deprecation notice througheZDebug::writeStrict()). - 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 a
doc/eng-us/bc/page.
Known exceptions
- Security defaults changed without opt-in. In September and October 2026 security headers,
HttpOnlyandSameSitesession cookies, a stricter upload check and new access requirements for some remote services were turned on by default (Security defaults, Behaviour changes of 16 to 30 September 2026). 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). @deprecatedAPIs inherited from eZ Publish 4 have no removal date; no removal is announced for the 6.0 line.
Releases and versioning
Version numbers
- The kernel version is in
lib/version.php(VERSION_MAJOR = 6,VERSION_MINOR = 0,VERSION_RELEASE = 15) and in the database rowezsite_dataezpublish-version, which the update SQL writes (for example6.0.15stable). - Releases of the 6.0 line are tagged
v6.0.<n>. The current line, 6.0.15, followsv6.0.14and is released as the tagv6.0.15once it is published (Changelog 6.0.15). - Only the last position counts on. After
x.y.9comesx.y.10, neverx.(y+1).0; moving a higher position is a decision about what the release means. Tags are sorted withgit tag -l 'v*' --sort=version:refname(orsort -V), because a plain name sort puts0.1.10before0.1.8. The rule is written down for extensions in Extensions, section 7 and for the Velocity engine in its changelog.
Tags are permanent
A published tag must never be moved, deleted or re-cut, and a published release must never be replaced. The packages are installed through Composer, which records a version once; a changed tag would give two different packages the same number. A bad release is corrected by the next one, whose notes say what was wrong. Before tagging: the working tree is clean, the tests pass, the version fields are bumped, the manifest matches.
Changelogs
- One page per release in
doc/changelogs/<series>/<version>.md(doc/changelogs/6.0/6.0.0.mdto6.0.15.md), extensions indoc/changelogs/extensions/. Entries are grouped as Added, Updated, Removed and Renamed; 6.0.15 additionally by period. Each page starts with Upgrading and links thedoc/eng-us/bc/pages. - Commit subjects use the same prefixes (
Added:,Updated:,Fixed:,Removed:,Renamed:); the CI job Commit messages of.github/workflows/quality.ymlchecks them with.githooks/check-commit-range(a warning only for outside contributors). - The full per-commit history is kept in
doc/eng-us/history/ledger/.
Extension versions
An extension release must write its version, without the v, into ezinfo.php ('Version') and
extension.xml (<metadata><version>), and into composer.json if it has a version, in the commit that the tag
points at; never tag first and bump afterwards. Check with php -l ezinfo.php and xmllint --noout extension.xml.
Extensions shipped inside the kernel repository carry the kernel version. Reference:
extension metadata.
The file manifest
share/filelist.md5 lists the checksum of every shipped file (about 9,500 lines). The admin upgrade check and
php bin/php/checkmanifest.php --all compare an installation against it. It must match the files of every
commit on the main branch: the CI job File manifest (share/filelist.md5) in .github/workflows/quality.yml fails on
main (and warns on a pull request) when it does not, and php bin/php/checkmanifest.php --fix (or
make manifest-fix) refreshes it. An extension with its own share/filelist.md5 refreshes it in the same release.
See File consistency check.
Known gaps
- The version constants in
lib/version.phpalready say15withVERSION_STATE = 'stable'while 6.0.15 is not released. doc/changelogs/README.mdstill points to an old upstream release page instead ofdoc/changelogs/6.0/.
Deployment standard
The two guides are the procedure; this section is the summary and the reasons for the order. Deploying covers serving a site with Apache and PHP-FPM, Velocity or FrankenPHP and shipping a change; Upgrading covers moving from 4.x, 5.x or an earlier 6.0.x.
Shipping a code change
After a change to a PHP class, an operator or an INI file, the steps must run in this order:
- Regenerate the class maps.
php bin/php/ezpgenerateautoloads.php -e(extensions); with-kfor the kernel when a kernel class was added or renamed.-kwalks the whole installation, so working copies inside it are excluded through.autoloadignoreor--exclude=<dir>. - Clear the settings cache.
php bin/php/ezcache.php --clear-tag=ini --allow-root-user(the tag clears both theiniand theglobal_inicaches). - Clear template caches when templates or template paths changed:
template,template-override,translation,design_base(--clear-id=...). - Load the new code into the web server. Reload the PHP-FPM service that really serves the site (on a server with
several PHP versions this is not always the one named
php-fpm;velocity.ini [DeploySettings] PhpFpmService,autoshipped) and restart Velocity (./console exp:velocity restart), whose workers keep the classes loaded at warm-up. - Clear the page caches last: the content view cache (
--clear-id=content), the HTTP cache, and Velocity's response cache (./console exp:velocity cache clear --apply). Clearing them before step 4 lets old code cache a page again.
./console exp:velocity deploy runs all of this in order (fourteen steps, PASS, FAIL or SKIP per step, exit status
1 on the first failure); --dry-run shows the steps, --kernel adds the kernel class map, --packer clears packed
scripts and styles. Details: Deploying a PHP change.
A template or stylesheet change needs only the template caches and Velocity's response cache, not a restart.
Upgrading an installation
- Back up files and database.
- Put the new code in place, regenerate the class maps and clear all caches
(
php bin/php/ezcache.php --clear-all --allow-root-user), then reload PHP-FPM and restart Velocity. - Apply the database update once, whole, in order:
update/database/<driver>/6.0/dbupdate-6.0.0-6.0.15.sql(MySQL, PostgreSQL and SQLite files exist; from 5.4,dbupdate-5.4.0-6.0.0.sqlfirst), then the scripts inupdate/common/scripts/6.0/the guide names (createaudittables.php,movetrashrecords.php; the directory also shipscreateapikeytable.php). - Read the checklist of every period passed in
doc/eng-us/bc/6.0/and the changelogs. - Check extensions:
./console exp:checkclassesreports classes PHP refuses to load. - Run the upgrade check: Setup > System upgrade, Check file consistency against
share/filelist.md5and Check database consistency against the schema files; both only read. From a shell:php bin/php/checkmanifest.php --all --extensions(The upgrade check).
Rules
- A deployment must reach every PHP runtime that serves the site; clearing caches alone leaves PHP-FPM and Velocity on the old classes.
- Database changes must ship as SQL for every supported driver in
update/database/<driver>/6.0/together with the schema inshare/db_schema.dba, and must say how to proceed on a database that already has some of them (for the 6.0.15 file: a statement for an existing column fails with its name, and only that statement is skipped). - A new class referenced from a shipped INI file should be guarded with
class_exists()in the kernel, because a Velocity worker started before the deploy does not know it.
Known gaps
- The database update files applied by hand leave no record of which statements ran;
exp:upgradeand the migrations (exp:migration:migrate, 6.0.15) apply and record every step. exp:velocity deploycovers PHP-FPM and Velocity on one machine; several web servers are deployed one by one.