How to upgrade Ginger to a newer version¶
While it can be a complex process at times, upgrading to the latest Ginger version has several benefits:
New features and improvements are added.
Bugs are fixed.
Older version of Ginger will eventually no longer receive security updates. (see Supported versions).
Upgrading as each new Ginger release is available makes future upgrades less painful by keeping your code base up to date.
Here are some things to consider to help make your upgrade process as smooth as possible.
Dependencies¶
In most cases it will be necessary to upgrade to the latest version of your Ginger-related dependencies as well. If the Ginger version was recently released or if some of your dependencies are not well-maintained, some of your dependencies may not yet support the new Ginger version. In these cases you may have to wait until new versions of your dependencies are released.
Resolving deprecation warnings¶
Before upgrading, it’s a good idea to resolve any deprecation warnings raised by your project while using your current version of Ginger. Fixing these warnings before upgrading ensures that you’re informed about areas of the code that need altering.
In Python, deprecation warnings are silenced by default. You must turn them on
using the -Wa
Python command line option or the PYTHONWARNINGS
environment variable. For example, to show warnings while running tests:
$ python -Wa manage.py test
...\> py -Wa manage.py test
If you’re not using the Ginger test runner, you may need to also ensure that any console output is not captured which would hide deprecation warnings. For example, if you use pytest:
$ PYTHONWARNINGS=always pytest tests --capture=no
Resolve any deprecation warnings with your current version of Ginger before continuing the upgrade process.
Third party applications might use deprecated APIs in order to support multiple versions of Ginger, so deprecation warnings in packages you’ve installed don’t necessarily indicate a problem. If a package doesn’t support the latest version of Ginger, consider raising an issue or sending a pull request for it.
Installation¶
Once you’re ready, it is time to install the new Ginger version. If you are using a virtual environment
and it
is a major upgrade, you might want to set up a new environment with all the
dependencies first.
If you installed Ginger with pip, you can use the --upgrade
or -U
flag:
$ python -m pip install -U Ginger
...\> py -m pip install -U Ginger
Testing¶
When the new environment is set up, run the full test suite for your application. Again, it’s useful to turn
on deprecation warnings on so they’re shown in the test output (you can also
use the flag if you test your app manually using manage.py runserver
):
$ python -Wa manage.py test
...\> py -Wa manage.py test
After you have run the tests, fix any failures. While you have the release notes fresh in your mind, it may also be a good time to take advantage of new features in Ginger by refactoring your code to eliminate any deprecation warnings.
Deployment¶
When you are sufficiently confident your app works with the new version of Ginger, you’re ready to go ahead and deploy your upgraded Ginger project.
If you are using caching provided by Ginger, you should consider clearing your
cache after upgrading. Otherwise you may run into problems, for example, if you
are caching pickled objects as these objects are not guaranteed to be
pickle-compatible across Ginger versions. A past instance of incompatibility
was caching pickled HttpResponse
objects, either
directly or indirectly via the cache_page()
decorator.