Documentation requirements for site packages
This part of the site packages help is for anyone who builds, changes or reviews a site installer package: a
developer forking sevenx_multisite, a designer shipping a starter site, a partner preparing a package for a
customer, or a reviewer of a pull request to the package server. It answers one question: what must a package
carry, and what should it carry, before it is published?
Every requirement here was taken from the code that reads a package (kernel/classes/ezpackage.php,
kernel/classes/ezpackageuploadinspector.php, kernel/classes/exppackagejson.php, the setup wizard steps in
kernel/setup/steps/) and from the 16 packages in the two 7x source repositories,
se7enxweb/sevenx-ezpackage (14 packages) and
se7enxweb/cjw_multisite-ezpackage (2 packages).
Contents
- Two kinds of requirement
- The checklist in short
- The pages of this part
- Where the requirements are checked
- Related pages
Two kinds of requirement
Each page marks every item with one of two labels:
| Label | Meaning | What happens when it is missing |
|---|---|---|
| Enforced | The code refuses the package, skips it, or stops the install | The import fails, the wizard does not list the package, or the install ends with an error |
| Convention | Every shipped 7x package does it, and the pages and tools that show a package rely on it | The package works, but a reader, a reviewer or a later release has less to go on |
A pull request to the package server is reviewed against both. "It imports" is the lowest bar, not the goal: see Contribute your site package.
The checklist in short
The full list with the reason for each item is The requirements checklist.
- To do: Enforced: the archive is a gzip compressed tar with
package.xmlat its top, only plain files and directories, no..and no absolute paths. - To do: Enforced:
<name>is letters, digits,_and-only, not starting with-. Convention: the.ezpkgfile carries the same name. - To do: Enforced (package upload in the administration):
<ezpublish>and<packaging>are present. - To do: Enforced:
<version><number>,<release>and<type value>are plain tokens of at most 64 characters. - To do: Enforced (setup wizard): a site package has
<type value="site" />, and every package it requires is listed in the sameindex.xmlwith aurl. - To do: Convention:
<vendor>,<summary>,<description>,<licence>,<state>, aLICENCEdocument, one changelog entry per release, a thumbnail in thedefaultfile collection. - To do: Convention: the package validates (
Validateon its page, orphp ezpm.php validate) before it is published. - To do: Convention: the source repository explains the package in a README and states its license.
The pages of this part
| Page | What it covers |
|---|---|
| The requirements checklist | Every item in one table, with its label and source |
| Required package.xml fields | The name rules, version tokens, <ezpublish>, <packaging>, vendor and type |
| License and documents | <licence>, documents/LICENCE, [LicenseSettings] |
| Changelog entries | <changelog><entry>, what the package page shows |
| Version numbers | <number> and <release>, how they are compared, the <ezpublish> version |
| Thumbnails and screenshots | files/default/thumbnail, thumbnail_url in index.xml |
| Declaring dependencies | <requires>, min-version, order, the flat list |
| Validating a package before publishing | Validate, the upload inspector, xmllint, ezpm.php validate |
| README and repository docs | What the source repository should carry |
Where the requirements are checked
A package meets the code at four points, and each checks a different set:
| Where | Code | Checks |
|---|---|---|
Every import (setup wizard download, ezpm.php import, administration upload) | eZPackage::importUnaudited() | Archive entries, a readable definition with a name, valid name, safe vendor directory, not already present |
Package upload in the administration (package/upload) | eZPackageUploadInspector::inspect(), then expPackageJson::validateDirectory() | Additionally: file suffix, gzip signature, size limits, <package> root, no DOCTYPE, <ezpublish> and <packaging>, every document well formed |
| The setup wizard's site type step | kernel/setup/steps/ezstep_site_types.php | Type site, the index entry, every required package downloadable and new enough |
| The create sites step | kernel/setup/steps/ezstep_create_sites.php | Every required package can be fetched and installed (errors EZSW-050, EZSW-051) |
Note
The setup wizard's own download and upload paths call eZPackage::import() directly, without the upload
inspector's definition checks. A package that imports through the wizard can still be refused by the
administration's upload page. Test both, as Validating a package before publishing
describes.
Related pages
- Site packages: start here
- Contribute your site package
- Glossary
- The package.xml reference
- The index.xml format
- Packages guide
- 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.