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.
-
Edit the file
includes/version.php
and update the version. -
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.
-
Edit the file
zc_install/sql/install/mysql_zencart.sql
and update the version number in theproject_version
andproject_version_history
tables. -
Edit the file
zc_install/sql/updates/mysql_upgrade_zencart_<current>.sql
and update the version number in theproject_version
andproject_version_history
tables. -
Ensure the version number in
zc_install/includes/systemChecks.yml
is the current version. -
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 version 2.1.0:
# | File | Version |
---|---|---|
1 | includes/version.php |
alpha: define('PROJECT_VERSION_MINOR', '1.0-alpha1'); |
final: define('PROJECT_VERSION_MINOR', '1.0'); |
||
2 | zc_install/includes/version.php |
alpha: define('PROJECT_VERSION_MINOR', '1.0-alpha1'); |
final: define('PROJECT_VERSION_MINOR', '1.0'); |
||
3 | zc_install/sql/install/mysql_zencart.sql |
alpha: project_version_major and project_version_minor for the two Zen-Cart Main rows should be 2 and 1.0-alpha1 .CHECK CAREFULLY - look at all rows |
final: project_version_major and project_version_minor for the two Zen-Cart Main rows should be 2 and 1.0 .CHECK CAREFULLY - look at all rows |
||
4 | zc_install/sql/updates/mysql_upgrade_zencart_210.sql |
alpha: project_version_major and project_version_minor should match the install file. project_version_comment for the two version rows should be Version Update 2.0.0->2.1.0-alpha1 CHECK CAREFULLY - look at all rows |
final: project_version_major and project_version_minor should match the install file. project_version_comment for the two version rows should be Version Update 2.0.0->2.1.0 CHECK CAREFULLY - look at all rows |
||
5 | zc_install/includes/systemChecks.yml |
Top checkDBVersion* block should look for version: '2.1.0' |
6 | zc_install/includes/version_upgrades.php |
'2.1.0'=>array('required'=>'2.0.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_210.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
Note: The actual PHP version we “support” is nowadays determined by what Laravel version we integrate. And that can be found in the laravel
directory’s composer.json
file. Then translate it from “8.0.2” to “80002”: 8.0.2 = 08.00.02 = 80002
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
(setTEXT_ERROR_PHP_VERSION
)zc_install/includes/systemChecks.yml
(setcheckPhpVersion
)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:
- Server Requirements in
user/first_steps/server_requirements.md
. - What’s New file for this release, e.g. What’s New in 1.5.8 under “About PHP Versions”. This file is in the
release
folder. README.md
under Zen Cart github home page
Other considerations:
/composer.json
/laravel
- long before release, the bundled Laravel code should match PHP dependencies- Update github workflows so tests run on desired versions
Copyright Updates
Do copyright updates in the following files:
- docs/INSTALL.TXT
- what’s new file for this release (Documentation site in
/release/
folder.) - changed files list for this release (Documentation site in
/release/
folder.)
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.