Version numbers
This page is for developers who release a site package or a package it requires. A package has several version fields, and they do different jobs: one decides whether a requirement is met, one is only shown, one is not read at all. Getting them right matters most for packages that other packages require, because the setup wizard compares versions to decide whether to download a package again.
Contents
- The version fields
- How a package version is read
- What the shipped packages use
- Traps
- Recommended form
- Related pages
The version fields
| Field | Where | Used for | Enforced |
|---|---|---|---|
| Version number | <version><number> | The package version, joined with the release | Must be a plain token, up to 64 of 0-9 A-Z a-z . _ + - |
| Release | <version><release> | The second half of the package version | The same token rule |
| Product version | <ezpublish><version> and <named-version> | Shown as "For Exponential" on the package page | Only that <ezpublish> exists (on package/upload) |
| Format version | version attribute of <package> | Nothing: parseDOMTree() does not read it | No |
| Index version | version attribute in index.xml | Shown on the setup wizard's site type step; compared with an imported package | No |
The token rule is eZPackage::isValidDefinitionToken() in kernel/classes/ezpackage.php; a definition that breaks
it is not read at all (Required package.xml fields).
How a package version is read
eZPackage::getVersion() joins the two halves with a hyphen: <number>-<release>. This pair is what
min-version in a <require> is compared with, and what the setup wizard compares between an imported package and
the index. The comparison is eZPackageVersion::compareFull() in kernel/classes/ezpackageversion.php:
- The part after the last hyphen is the release number only when it is all digits.
1.0-1is version1.0, release1. Otherwise the whole text is the version number, with no release. - Version numbers compare by Semantic Versioning 2.0.0 precedence. Older forms are read too:
1and1.0as1.0.0,1.2.3.4with the fourth part after PATCH,3.4.0beta1as the prereleasebeta1. - A version with a prerelease comes before the same version without one. Prerelease identifiers compare one by one: numeric ones numerically, others in ASCII order.
- The release numbers compare last, numerically, a missing one as
0:1.0-1<1.0-2<1.0.1-1.
What the shipped packages use
Checked in the two 7x source repositories on 2026-10-18:
| Packages | <number> | <release> | <ezpublish><version> |
|---|---|---|---|
The 5 site packages, cjw_multisite_democontent, both sevenx_multisite_democontent packages | 6.0 | 15-stable | 6.0.15-stable |
sevenx_democontent | 6.0 | 14-stable | 6.0.14-stable |
sevenx_banners, sevenx_classes, sevenx_democontent_clean, the three sevenx_design_* | 6.0 | 10-stable | 6.0.10-stable |
sevenx_extension | 6.0 | 6.0.15-stable | 6.0.15-stable |
The release follows the patch number of an Exponential 6.0 release (10, 14, 15), the same release <ezpublish><version> names. The site packages require their
dependencies with min-version="5.1" or min-version="1.0", and in the 6.0.15 index.xml the 7x site packages
are listed with version="6.0-15-stable", the same text as their <number>-<release> (until 2026-10-19 the four 7x
site packages were listed as 1.0.0-0 and cjw_multisite as 6.0.15-0).
Traps
A release with a state word (fixed in 6.0.15). From 6.0.15 on, compareFull() reads digits followed by a state
word as a release: 6.0-15-stable (and 6.0-15stable) is version 6.0, release 15. A stable word (stable,
final, release, ga) means no prerelease, so 6.0-15-stable equals 6.0-15 and meets a min-version="6.0".
Any other word makes a prerelease of that release: 6.0-15-rc1 < 6.0-15. The same stable words after a legacy
version number (6.0.15stable, 1.0-final) are not a prerelease either.
Note
Before 6.0.15 a release that was not all digits was no release: 6.0-15-stable was read as the version 6.0.0
with the prerelease 15-stable, lower than 6.0, so a min-version="6.0" was not met, and the wizard treated
the imported package as too old. Releases also compared as text then (9-stable above 15-stable); from 6.0.15
on they compare as numbers. An installation older than 6.0.15 still reads them the old way, so a package meant for
one should keep asking for 5.1 or 1.0, as the shipped site packages do.
The index version is compared too. When the index lists a higher version than an imported package has, the
site type step offers the index entry instead of the imported one (eZStepSiteTypes::createSitePackagesList()).
In kickstart mode the index entry is always preferred. Keep the index version equal to the package's
<number>-<release>.
The product version is not a compatibility check. Nothing compares <ezpublish><version> with the running
release. Say in the description and the source repository's README which releases a package is meant for.
Recommended form
For a new package or a new release of your own:
- To do:
<number>: Semantic Versioning, three numbers (1.0.0,1.2.0). The creation wizards insist on this: at most 24 characters, because theezpackagetable stores<number>-<release>in 30 (eZPackageVersion::MAX_NEW_LENGTH). - To do:
<release>: a whole number,1for the first build of a version, raised when the same version is packaged again. - To do:
<ezpublish><version>: the Exponential release you built and tested it on, such as6.0.15-stable, with<named-version>6.0</named-version>. - To do: The
versionattribute inindex.xml: the same<number>-<release>. - To do: The changelog entry's
releaseattribute: the same release (Changelog entries). - To do: A
min-versionin a site package that names a version the required package really has, written the same way.
<version>
<number>1.2.0</number>
<release>1</release>
</version>How to number your own releases over time is on Versioning your own packages. The settings and the wizard side are in Package licenses and Semantic Versioning.
Related pages
- Documentation requirements for site packages
- Declaring dependencies
- Required package.xml fields
- The index.xml format
- Semantic Versioning 2.0.0
- Site packages: start here
- 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.