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.