Until version 1.0.0, sheraf is considered as beta, and while we do all we can to make upgrades as smooth as possible, bugs and breaking changes still have a chance to occur.
How to install?
pip install sheraf
There are several variants of the sheraf package:
sheraf[zeo]installs the dependencies to work with ZEO.
sheraf[relstorage]installs the dependencies to work with relstorage.
sheraf[all]installs all those dependencies.
Bugfix versions are non-breaking. You can upgrade from a bugfix version to another directly (from
X.Y.B). No checks, no code change, and no migration are required.
Minor versions deprecate and smoothly break the code compatibility, but they do not break the data compatibility. To migrate from a minor version to another (from
X.B.*) you need to:
Make sur the version you target is consecutive to the version you have. For instance, if you have sheraf
3.4and want to upgrade to
3.7, you first need to upgrade to
3.5, then you need to upgrade to
3.6before you are able to upgrade to
Make sure that you are using the last bugfix version of your minor version. For instance, if you are using sheraf
3.5.6and want to upgrade to
3.6, you need to upgrade to
Read the changelog for every intermediary version between you current version and the new one (i.e. everything from
Run your unit tests, and fix all the
DeprecationWarningyour test runner reports;
Facultatively, check and fix your database in all your production environments with
print_health(); This step is not required.
Upgrade to the new minor version you target. It is recommended that you upgrade to the most recent bugfix version of the new minor version. For example, once you are at
3.5.10, upgrade directly to
If you do not cover enough code with you unit tests, you may not trigger all the
DeprecationWarning you need to fix to be able to upgrade. This is your responsability to have your code well covered.
Major version break code and data compatibility. Migrations and manual interventions are needed to upgrade. To migrate from a major version to another (from
B.*.*) you need to:
Upgrade consecutively to all the minor versions separating you from the major version you target;
You NEED to check and fix your database in all your production environments with
Then upgrade to the major version. Read the Changelog with attention, it may have further recommendations.
How to contribute?
Use your brain and your keyboard to produce code.
Use black to format your code.
Use docformatter to format the documentation.
Check that tox agrees with your modifications.