How to upgrade GingerDJ to a newer version

While it can be a complex process at times, upgrading to the latest GingerDJ version has several benefits:

  • New features and improvements are added.

  • Bugs are fixed.

  • Upgrading as each new GingerDJ 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 GingerDJ-related dependencies as well. If the GingerDJ version was recently released or if some of your dependencies are not well-maintained, some of your dependencies may not yet support the new GingerDJ 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 GingerDJ. 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 GingerDJ 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 GingerDJ before continuing the upgrade process.

Third party applications might use deprecated APIs in order to support multiple versions of GingerDJ, so deprecation warnings in packages you’ve installed don’t necessarily indicate a problem. If a package doesn’t support the latest version of GingerDJ, consider raising an issue or sending a pull request for it.

Installation

Once you’re ready, it is time to install the new GingerDJ 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 GingerDJ with pip, you can use the --upgrade or -U flag:

$ python -m pip install -U GingerDJ

...\> py -m pip install -U GingerDJ

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 GingerDJ by refactoring your code to eliminate any deprecation warnings.

Deployment

When you are sufficiently confident your app works with the new version of GingerDJ, you’re ready to go ahead and deploy your upgraded GingerDJ project.

If you are using caching provided by GingerDJ, 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 GingerDJ versions. A past instance of incompatibility was caching pickled HttpResponse objects, either directly or indirectly via the cache_page() decorator.