When the database schema (the database user version number) changes, the API in the core QCoDeS repository also changes to produce output matching the new version. That, in turn, makes the official API incapable of generating databases of older versions. To the end of testing the upgrade functions, we would like to be able to generate old version databases. The purpose of the legacy_DB_generation folder is contain scripts that generate old-version databases for the tests to consume.
When a new corner-case that we want to test for is discovered, we extend the scripts to produce a .db-file covering that case. When a new version upgrade is launched, we make a new script to generate .db-files for that version upgrade to test itself on.
The scripts use gitpython to roll QCoDeS back to a relevant old commit and create database files with the ancient source code.
The scripts should not be run as a part of the QCoDeS test suite, but prior to test execution in a different process. The scripts have some dependencies and will run in the normal QCoDeS environment PROVIDED that QCoDeS was installed with the editable flag (i.e. pip install -e <path-to-qcodes>). The output of the scripts should be committed to the qcodes_db_fixtures as this git repo is automatically included as a submodule of qcodes for use in the test suite.
First, please check if there is already a script producing .db-files of your desired version. If so, simply extend that script to produce a .db-file covering your particular test case. If not, follow this checklist:
- Identify the database version of which you would like to create one or more .db-files. Let's call that "your version".
- Check the variable
GIT_HASHESinutils.pyto see if "your version" already has a recorded commit hash.- If not, search through the
git logofmasterto find the merge commit just before the merge commit that introduces the next version after "your version". Put that first commit intoGIT_HASHESalong with the version number of "your version".
- If not, search through the
- Make a script called
generate_version_<your_version>.py. Copy the general structure ofgenerate_version_0.py. Make your generating functions take ZERO arguments and do all their imports inside their own scope.
Remember to update the tests to use your newly generated fixtures. A test must skip (not fail) if the fixture is not present on disk. The new database fixtues should be added to qcodes_db_fixtures and you should make sure to upgrade the submodule reference within QCoDeS to point to the latest commit of qcodes_db_fixtures that includes the new fixtures.