This page describes the process to create a new upgrade script for the next release.
It assumes that the major_version
, minor_version
, and update_version
macros
in pki.spec have been updated for the next release.
Upgrade scripts are organized by version numbers in base/server/upgrade folder.
The new upgrade script needs to be stored in base/server/upgrade/<version>
folder
where the <version>
is the <major>.<minor>.<update>
version of the next release.
If the folder does not exist, create the folder.
The upgrade scripts for each version are sorted by 2-digit index numbers in the filename (i.e. <index>-<name>.py
).
To determine the index number of the new upgrade script, find the index number of the last upgrade script
in base/server/upgrade/<version>
folder, then increment by 1
.
If this is the first upgrade script for the version, use index number 01
.
Once the upgrade folder and the index number have been determined,
create the upgrade script (i.e. <index>-<name>.py
) in base/server/upgrade/<version>
folder:
class <name>(pki.server.upgrade.PKIServerUpgradeScriptlet): def __init__(self): super().__init__() self.message = ... ...
Make sure the class name matches the <name>
in the filename.
See examples in base/server/examples/upgrade. See also existing upgrade scripts in base/server/upgrade.
To quickly test the upgrade script, install the script manually:
$ mkdir -p /usr/share/pki/server/upgrade/<version> $ cp base/server/upgrade/<version>/<filename> /usr/share/pki/server/upgrade/<version>
Then run the upgrade in verbose mode:
$ pki-server upgrade -v
Finally, verify the changes made by the upgrade script. If there are issues, the error messages will appear in the standard error.
To test the upgrade script properly, follow these steps:
-
install a build that has been released
-
create a new server instance
-
create a new build that contains the new upgrade script
-
install the new build
-
restart the server instance
Finally, verify the changes made by the upgrade script. If there are issues, the error messages will appear in systemd journal.
When cherry-picking a commit that contains an upgrade script to another branch, use the same process to determine the upgrade folder and the index number based on the next version to be released from that branch. Move and rename the upgrade script accordingly.
If a package is rebased to a new version that contains a new upgrade script, the script should already be in the right folder and has the right index number assuming that the above procedure was followed correctly.
If the package is patched instead (i.e. maintaining the same version number), use the same process to determine the upgrade folder and the index number based on the version of the package. Update the patch to move and rename the upgrade script accordingly.