Shedding light on Django versioning

As of version 2.0 released in 2017, Django uses a loose form of semantic versioning, but what exactly does that mean? This article dives into the details of Django’s release cycle and related policies to answer some on the crucial questions, such as:

• What we can expect from each version in the release series?
• Does Django break things? if so, when?
• How long is each version supported?
• What’s Django policy for supporting Python versions?

Let’s start with a brief description on each release series.

Release cycle

Django releases come in series, and each series contains three releases. The leading numbers of each series are consecutive and have no special meaning. Django contributors work now on 5.X series, the next one will be 6.X, and so on. The current series (like any other in the future) will contain three releases:

• 5.0 (released on December 4, 2023)
• 5.1 (planned for August, 2024)
• 5.2 - Long Term Support (planned for April 2025)

A new feature release (X.Y) is issued every 8 months. It is preceded by almost 3 months of pre-releases (alpha, beta, release candidate) before the final version is released. So please don’t hesitate and test pre-releases to help bulletproofing the final version 🐛

Moreover, you should be aware that each X.Y release brings tons of new features and smaller improvements, so do not expect that e.g. 5.0 will differ significantly from 5.1 or 5.2 in this matter. Each new version is the best Django ever!

After release, every version (including LTS) is in the mainstream support for exactly 8 months, what means that a minor version (X.Y.Z) containing bugfixes will be issued for them at the beginning of each month. Django has a strict backporting policy so only specific bugfixes are backported to already released versions, which includes:

• security patches,
• data loss and crashing bugs,
• bugs in the new features,
• regressions from older versions introduced in the current release series.

Once a release reaches the end of mainstream support it enters into extended support for another 8 months for a normal release (X.0 and X.1), and 28 months - for an LTS (X.2). That’s right, the total support period for the LTS versions is 3 years! Please note that only security patches and data loss bugs are fixed during the extended support.

For example, a regression introduced in Django 4.2 that was reported in January, 2024 (so when it’s already in extended support) will be only fixed in Django 5.1+ 🙀 This policy is really strict and can be scary at the beginning, but it helps protect Django and makes bumping versions really smooth. This is also why it’s so important to upgrade your Django before it reaches the end of the mainstream support. Django rewards early adopters!

When we choose our tech stack we need to answer a few key questions. Is it mature and stable? Does this break things? If so, will we have time to prepare for it? The next section answers these questions.

Stability

Django is truly committed to its stability policy, so much so that it becomes one of its main advantages. Anything that is considered part of the public API cannot be changed without appropriate deprecation, which includes clear documentation, existing upgrade paths, and cannot be done undetected by raising deprecation warnings. Let’s take a look at key points of Django policy:

• deprecated features will continue to work in a backward compatible manner throughout the series in which they were deprecated,
• deprecated features are never removed in LTS releases,
• deprecation is done over at least 2 feature releases.

How it works in practice?

• Features deprecated in 5.0 will be removed in 6.0 (2 years later).
• Features deprecated in 5.1 will be removed in 6.0 (16 months later).
• Features deprecated in 5.2 (LTS) will be removed in 6.1 (16 months later).

It’s heartwarming that we have plenty of time to deal with potentially breaking changes.

Django is a Python web framework, so it requires Python and it loves Python. Django is also very generous when it comes to the variety of Python versions that are supported by each release. Let’s check it in detail.

Python support

Django is one of the early adopters of new versions of Python. It’s checked daily against all latest pre-releases (starting from the very first alpha of each Python version). This approach allows Django to add official support for the latest Python as soon as it’s released. Moreover, it’s added not only to the latest Django version, but to all versions under mainstream support, e.g. support for Python 3.12 was added to Django 4.2 in version 4.2.8, so the last bugfix release for its mainstream support.

What about dropping support for old Python versions? Django is really careful here, proving once again that it cares about developers and takes stability seriously. Support for old Python versions is dropped only in the first release of each series (e.g. 5.0) which has two big advantages:

• we can upgrade Django to the newest version in the same series without struggling with a Python upgrade, as all of them (X.0, X.1, X2 - LTS) will support (at least) all Python versions supported by the first one (X.0). For example:

• if upgrading the Python version is somehow problematic for us, we can still use a previous LTS (X.2) version, and have 2+ more years of extended support to handle it.

Closing thoughts

Django versioning can be tricky to understand at first glance. However, when we discover and understand the reasons behind it, it becomes clear why it looks that way. Creating releases in clear and predictable series, makes life easier for developers and proves that Django really cares about them. Stability is one the greatest advantages of Django, making it the obvious choice for web developers for many years.