Prerequisites

To run the release process, you must have the following:

  • Running at least PHP 8.1. (This means php -v must run without an alias and must show php 8.1 or higher.) Here are guidelines for upgrading to PHP 8.1 on a Mac.

  • Maintainer access to the Zen Cart github repository.

  • A local copy of the VersionStamper application.

  • Admin access to the main Zen Cart website

  • Admin access to the Server Manager (https://servermanager.zen-cart.com/)

  • an up to date copy of the master branch for Zen Cart.

  • an up to date copy of the documentation repo.

Once you have these things, you’re almost ready to begin.

Final Steps Before Beginning

Prepare your branch

Be sure your copy of the Github repo is up to date, and be sure you’re on the right branch for building (either master or prior-version-branch for a patch).

Create a new branch specifically for the version file changes.

Update the versioning files:

NOTE: If you are setting up a pre-release, please see Pre-Release Notes.

Remember we are using Semantic Versioning in post 2.0 releases. So a reelease number is MAJOR.MINOR.PATCH.

  1. Edit the file includes/version.php and update the version.

  2. Edit the file zc_install/includes/version.php and update the version.

For patch releases or any release with no database change SKIP REMAINING VERSION FILE UPDATES. Go to the next step.

  1. Edit the file zc_install/sql/install/mysql_zencart.sql and update the version number in the project_version and project_version_history tables.

  2. Edit the file zc_install/sql/updates/mysql_upgrade_zencart_<current>.sql and update the version number in the project_version and project_version_history tables.

  3. Ensure the version number in zc_install/includes/systemChecks.yml is the current version.

  4. Ensure the new version number has been added to zc_install/includes/version_updates.php.

The thing to remember is that the database version does not include the patch number / letter, because the database doesn’t change just because of a patch release.

Here’s what should be in these files for a (hypothetical) version 2.2.3 build:

# File Version
1 includes/version.php alpha: define('PROJECT_VERSION_MINOR', '2.3-alpha1');
final: define('PROJECT_VERSION_MINOR', '2.3');
2 zc_install/includes/version.php alpha: define('PROJECT_VERSION_MINOR', '2.3-alpha1');
final: define('PROJECT_VERSION_MINOR', '2.3');
alpha and final: define('EXPECTED_DATABASE_VERSION_MINOR', '2.0');
DB version ends in zero always; doesn’t change because of a patch release.
3 zc_install/sql/install/mysql_zencart.sql Variables now specify database and project version major and minor numbers.
For database, do not specify patch version! CHECK CAREFULLY - look at all variables.
This new system was introduced in 2.2.1; in older releases, the version information was repeated.
4 zc_install/sql/updates/mysql_upgrade_zencart_220.sql See above.
5 zc_install/includes/systemChecks.yml Top checkDBVersion* block should look for version: '2.2.0'
6 zc_install/includes/version_upgrades.php '2.2.0'=>array('required'=>'2.1.0'),

Shortcut for editing these 6 files:

vi includes/version.php zc_install/includes/version.php zc_install/sql/install/mysql_zencart.sql zc_install/sql/updates/mysql_upgrade_zencart_220.sql zc_install/includes/systemChecks.yml zc_install/includes/version_upgrades.php

Note that in most cases, includes/version.php and zc_install/includes/version.php will be identical.

There are other version related updates to do, but they’re not part of the build, so they are detailed in post release tasks.

For Major Releases - Update the Implementation Guide

The implementation guide (docs/implementation-guide.pdf) is part of the build and should be updated before the build begins. See Implementation Guide.

This is mentioned on the next page as well as a reminder, since it’s easy to forget.

For Major Releases - set the PHP Version range

Update these places:

Uses of PHP_VERSION_ID (for the minimum version):

  • zc_install/index.php
  • includes/application_top.php
  • admin/includes/application_bootstrap.php
  • admin/includes/application_top.php

Other Code Files:

  • zc_install/includes/languages/en_us/main.php (set TEXT_ERROR_PHP_VERSION)
  • zc_install/includes/systemChecks.yml (set checkPhpVersion)
  • zc_install/index.php (only change if zc_install itself needs a newer PHP version: we want zc_install to run for inspection even on older PHP)

Documentation Files:

Other considerations:

  • /composer.json
  • Update github workflows so tests run on desired versions

Do copyright updates in the following files:

  1. docs/INSTALL.TXT
  2. what’s new and changes files list for this release (common footer in doc repo /layouts/shortcodes/release_footer.md.)

Check in!

You’ll want to check in all these changes so they get version stamped correctly. Merge the branch you created for these changes.



Still have questions? Use the Search box in the upper right, or try the full list of FAQs. If you can't find it there, head over to the Zen Cart support forum and ask there in the appropriate subforum. In your post, please include your Zen Cart and PHP versions, and a link to your site.

Is there an error or omission on this page? Please post to General Questions on the support forum. Or, if you'd like to open a pull request, just review the guidelines and get started. You can even PR right here.
Last modified March 20, 2026 by Scott Wilson (54c6ccdb).