Version Stamping
Version stamping consists of a number of processes that are actioned on files that have changed in the release.
Those actions are
- Update the copyright year in the header of the fie to the current year.
- Add/Update the details of what release the file was added/modified
- Create a list of files that were added/deleted or modified and sort into those sections.
For this we use a Php script to automate this process.
The script is available in the https://github.com/zencart/zencart-release-process repository.
This is a private repository, so you may need to request access.
You need to create a feature branch for the version stamping changes, e.g.
git checkout -b version-stamping-v158-alpha
Installing
Clone the https://github.com/zencart/versionstamper repository to your local computer.
While there are some basic intall instruction in the readme.md for VersionStamper more explicit instructions follow.
clone repository
copy config.example.php to config.php
composer install
config file
'newVersion' => 'v1.5.8-alpha', // note at this point we don't have to have a tag
'commitDate' => '2022', //the date that will be used for the updatecommit
'copyrightDate' => '2022', //the date that will be used for the copyright date
'firstHash' => 'c80dc0f2f88e3d461fca826a0a42aa5567a9dfcc', // usually the hash of tagged prior release
'lastHash' => '81782eb678d072952ad919629e0352c77a49aaba', // usually the hash of the last commit for this new release
'ignoreDirectories' => ['includes/classes/vendors', '.circleci', '.github', 'laravel'],
'rootPath' => '/home/wilt/Projects/zencart/'
];
- newVersion - the version name of the release being worked on e.g. v1.5.8-alpha
- commitDate - the year to use for updating the commit date - will be deprecated for auto setting
- copyrightDate - the tear to use for the copyright date - will be deprecated for auto setting
- firstHash - the hash of the first commit in this branch - see below
- lastHash - the hash of the first commit in this branch - see below
- ignoreDirectories - a list of directories to ignore for changes
- rootPath - the absolute path to your Zen Cart checkout
firstHash
The firstHash
represents the point which the release being worked on was branched from master
This can sometimes be difficult to find manually.
We can do something like
git rev-list --ancestry-path $(git merge-base main v158)..v158 | tail -1
replacing v158
with the version we are working on
@FIXME need better instructions for getting first hash.
note: this assumes all versions prior were merged into master, and while the above is using a branch name, we may need to use a tag name where there are multiple releases within a branch.
lastHash
This is the hash of the last commit to the branch we are working on. Can be found by looking at the github commits for our branch
executing version stamper
php versionstamp.php app:version-stamp
This will run the version stamper in debug mode> e.g. It will output information about the changes it would make, without altering any files.
We could also do
php versionstamp.php app:version-stamp > somefile.txt
to create a log of proposed changes that we could review
To actually make changes we would use
php versionstamp.php app:version-stamp --mode=run
Remember that we should create a feature branch to encapsulate these changes, rather than running directly against our working branch.
Once the version stamping is complete, you will need to go to your Zen Cart checkout and commit and merge the changes created by the version stamping
There is a section of these docs called Release Notes, in which you should capture some basic information about the release progress.