At some point in a project’s life cycle you’ll find it necessary to upgrade the software libraries or frameworks you’ve used. Upgrading the Django version used in your projects can offer you a number of useful (new features) and vital (security fixes) benefits.
In this guide we will take a look at what’s need to upgrade a project to the new version of the Django framework. The useful resources are summarised at the end of this article.
Carefully plan the upgrade
Check the Django release notes for the version you’re upgrading to. If you’re upgrading to version 1.9 for example, you should check out the complete release notes here.
The release notes for a major version contain a section on backwards incompatible changes, deprecated features and removed features. You should never use features that are deprecated, although they will continue to work for this version it’s not a very sensible thing to keep writing code that uses these features just so you have to remove them later.
A very important resource you should know is the official Django deprecation timeline. This document contains a list of future Django versions and what features will be deprecated or removed by then.
In fact, it’s a good idea to read release notes even for minor version upgrades. So if you’re doing an upgrade to version 1.9.2 when your project is at version 1.9.0, read the release notes anyway.
Using the information you get from the release notes you should start to compile a list of items that you have to modify in the codebase of your project. At present this list will contain the deprecated features, the removed features and other information that is vital when upgrading to the next version.
I don’t recommend that you add new features to this list. While it may seem tempting to start using new features at this point, just cause you’re already in the code, it will only muddy things for the upgrade. Keep the new stuff in the back of your mind or on another list and start working on them after you upgrade the Django version.
Start a new branch in your version control system
Just like with all work, big or small, create a separate branch for it in your VCS. From your main branch, create a new branch specifically for this upgrade. You don’t know how smooth the upgrade will go, it might take you a couple of hours or you could spend the next two weeks hunting down some serious bugs. Having everything in a separate branch will ensure that things to smoothly for you and your project.
Upgrade the Django Framework
If you’re using pip for package management you can easily upgrade using a pip install -U Django The latest version of the framework will be installed and you can start your code upgrade.
If for some absurd reason you aren’t using pip (or similar tool) to manage your python packages and you have to perform a manual installation, don’t worry. Just like the official Django documentation I recommend that completely uninstall the previous Django version from your virtualenv/system and perform a new install of the latest version.
Upgrade your project’s code
Now we get to the real work, upgrading your projects’s code. When doing Django version upgrades I found this to be the most wierd step. Sometimes you move through it unscathed, finish testing and just deploy. Other times you spend many hours, nights and mornings hunting that one line of code that keeps screwing with things.
With your list of items you compiled in our first step, locate all code that needs to be changed. I recommend incremental changes where you first tackle the items where a feature was removed (and will essentially always break your project), followed by any unforeseen changes you need to make just because. When you project passes all tests (see the next step) and could be deployed, then you start working on the deprecated features and fix them.
Test your project before and after the upgrade
Before upgrading the Django version of your project, run your tests. You do have tests right? Unit tests, integration tests, the whole works?
After finishing the upgrade, run your tests again and verify that everything still works. Realistically you will need to perform extra manual tests. I’ve never seen a project that has 100% complete test coverage (both unit, integration and functional), so prepare for a couple of hours of manual testing.
When manually testing your project, it really helps to have a set of user stories or use cases written down for you to follow. Not only are user stories a vital part of software design, during test fases like this they are essential to covering your ass and avoiding hectic post-deployment debugging sessions.
Deploy the new version
After you finished testing and have sufficiently convinced yourself that everything still works, you’re ready for deployment. Check if your current deployment proces, script or tools are suited for a major upgrade. Backup up your production database and any user created data. Press Execute.
Now there’s nothing much for you to do except keep an eye out on your monitoring tools and log files. Congratulations!
The list below contains all resources we touch upon in this article. Bookmark this list so you can check back in the future when you have a Django version upgrade to perform!