| 1 |
======================== |
| 2 |
Django's release process |
| 3 |
======================== |
| 4 |
|
| 5 |
.. _official-releases: |
| 6 |
|
| 7 |
Official releases |
| 8 |
================= |
| 9 |
|
| 10 |
Since version 1.0, Django's release numbering works as follows: |
| 11 |
|
| 12 |
* Versions are numbered in the form ``A.B`` or ``A.B.C``. |
| 13 |
|
| 14 |
* ``A.B`` is the *feature release* version number. Each version will be mostly |
| 15 |
backwards compatible with the previous release. Exceptions to this rule will |
| 16 |
be listed in the release notes. |
| 17 |
|
| 18 |
* ``C`` is the *patch release* version number, which is incremented for bugfix |
| 19 |
and security releases. These releases will be 100% backwards-compatible with |
| 20 |
the previous patch release. The only exception is when a security or data |
| 21 |
loss issue can't be fixed without breaking backwards-compatibility. If this |
| 22 |
happens, the release notes will provide detailed upgrade instructions. |
| 23 |
|
| 24 |
* Before a new feature release, we'll make alpha, beta, and release candidate |
| 25 |
releases. These are of the form ``A.B alpha/beta/rc N``, which means the |
| 26 |
``Nth`` alpha/beta/release candidate of version ``A.B``. |
| 27 |
|
| 28 |
In git, each Django release will have a tag indicating its version number, |
| 29 |
signed with the Django release key. Additionally, each release series has its |
| 30 |
own branch, called ``stable/A.B.x``, and bugfix/security releases will be |
| 31 |
issued from those branches. |
| 32 |
|
| 33 |
For more information about how the Django project issues new releases for |
| 34 |
security purposes, please see :doc:`our security policies <security>`. |
| 35 |
|
| 36 |
.. glossary:: |
| 37 |
|
| 38 |
Feature release |
| 39 |
Feature releases (A.B, A.B+1, etc.) will happen roughly every eight months |
| 40 |
-- see `release process`_ for details. These releases will contain new |
| 41 |
features, improvements to existing features, and such. |
| 42 |
|
| 43 |
Patch release |
| 44 |
Patch releases (A.B.C, A.B.C+1, etc.) will be issued as needed, to fix |
| 45 |
bugs and/or security issues. |
| 46 |
|
| 47 |
These releases will be 100% compatible with the associated feature release, |
| 48 |
unless this is impossible for security reasons or to prevent data loss. |
| 49 |
So the answer to "should I upgrade to the latest patch release?" will always |
| 50 |
be "yes." |
| 51 |
|
| 52 |
Long-term support release |
| 53 |
Certain feature releases will be designated as long-term support (LTS) |
| 54 |
releases. These releases will get security and data loss fixes applied for |
| 55 |
a guaranteed period of time, typically three years. |
| 56 |
|
| 57 |
See `the download page`_ for the releases that have been designated for |
| 58 |
long-term support. |
| 59 |
|
| 60 |
.. _the download page: https://www.djangoproject.com/download/ |
| 61 |
|
| 62 |
.. _internal-release-cadence: |
| 63 |
|
| 64 |
Release cadence |
| 65 |
=============== |
| 66 |
|
| 67 |
Starting with Django 2.0, version numbers will use a loose form of `semantic |
| 68 |
versioning <https://semver.org/>`_ such that each version following an LTS will |
| 69 |
bump to the next "dot zero" version. For example: 2.0, 2.1, 2.2 (LTS), 3.0, |
| 70 |
3.1, 3.2 (LTS), etc. |
| 71 |
|
| 72 |
SemVer makes it easier to see at a glance how compatible releases are with each |
| 73 |
other. It also helps to anticipate when compatibility shims will be removed. |
| 74 |
It's not a pure form of SemVer as each feature release will continue to have a |
| 75 |
few documented backwards incompatibilities where a deprecation path isn't |
| 76 |
possible or not worth the cost. Also, deprecations started in an LTS release |
| 77 |
(X.2) will be dropped in a non-dot-zero release (Y.1) to accommodate our policy |
| 78 |
of keeping deprecation shims for at least two feature releases. Read on to the |
| 79 |
next section for an example. |
| 80 |
|
| 81 |
.. _internal-release-deprecation-policy: |
| 82 |
|
| 83 |
Deprecation policy |
| 84 |
================== |
| 85 |
|
| 86 |
A feature release may deprecate certain features from previous releases. If a |
| 87 |
feature is deprecated in feature release A.x, it will continue to work in all |
| 88 |
A.x versions (for all versions of x) but raise warnings. Deprecated features |
| 89 |
will be removed in the B.0 release, or B.1 for features deprecated in the last |
| 90 |
A.x feature release to ensure deprecations are done over at least 2 feature |
| 91 |
releases. |
| 92 |
|
| 93 |
So, for example, if we decided to start the deprecation of a function in |
| 94 |
Django 4.2: |
| 95 |
|
| 96 |
* Django 4.2 will contain a backwards-compatible replica of the function which |
| 97 |
will raise a ``RemovedInDjango51Warning``. |
| 98 |
|
| 99 |
* Django 5.0 (the version that follows 4.2) will still contain the |
| 100 |
backwards-compatible replica. |
| 101 |
|
| 102 |
* Django 5.1 will remove the feature outright. |
| 103 |
|
| 104 |
The warnings are silent by default. You can turn on display of these warnings |
| 105 |
with the ``python -Wd`` option. |
| 106 |
|
| 107 |
A more generic example: |
| 108 |
|
| 109 |
* X.0 |
| 110 |
* X.1 |
| 111 |
* X.2 LTS |
| 112 |
* Y.0: Drop deprecation shims added in X.0 and X.1. |
| 113 |
* Y.1: Drop deprecation shims added in X.2. |
| 114 |
* Y.2 LTS: No deprecation shims dropped (while Y.0 is no longer supported, |
| 115 |
third-party apps need to maintain compatibility back to X.2 LTS to ease |
| 116 |
LTS to LTS upgrades). |
| 117 |
* Z.0: Drop deprecation shims added in Y.0 and Y.1. |
| 118 |
|
| 119 |
See also the :ref:`deprecating-a-feature` guide. |
| 120 |
|
| 121 |
.. _supported-versions-policy: |
| 122 |
|
| 123 |
Supported versions |
| 124 |
================== |
| 125 |
|
| 126 |
At any moment in time, Django's developer team will support a set of releases to |
| 127 |
varying levels. See `the supported versions section |
| 128 |
<https://www.djangoproject.com/download/#supported-versions>`_ of the download |
| 129 |
page for the current state of support for each version. |
| 130 |
|
| 131 |
* The current development branch ``main`` will get new features and bug fixes |
| 132 |
requiring non-trivial refactoring. |
| 133 |
|
| 134 |
* Patches applied to the main branch must also be applied to the last feature |
| 135 |
release branch, to be released in the next patch release of that feature |
| 136 |
series, when they fix critical problems: |
| 137 |
|
| 138 |
* Security issues. |
| 139 |
|
| 140 |
* Data loss bugs. |
| 141 |
|
| 142 |
* Crashing bugs. |
| 143 |
|
| 144 |
* Major functionality bugs in new features of the latest stable release. |
| 145 |
|
| 146 |
* Regressions from older versions of Django introduced in the current release |
| 147 |
series. |
| 148 |
|
| 149 |
The rule of thumb is that fixes will be backported to the last feature |
| 150 |
release for bugs that would have prevented a release in the first place |
| 151 |
(release blockers). |
| 152 |
|
| 153 |
* Security fixes and data loss bugs will be applied to the current main branch, |
| 154 |
the last two feature release branches, and any other supported long-term |
| 155 |
support release branches. |
| 156 |
|
| 157 |
* Documentation fixes generally will be more freely backported to the last |
| 158 |
release branch. That's because it's highly advantageous to have the docs for |
| 159 |
the last release be up-to-date and correct, and the risk of introducing |
| 160 |
regressions is much less of a concern. |
| 161 |
|
| 162 |
As a concrete example, consider a moment in time halfway between the release of |
| 163 |
Django 5.1 and 5.2. At this point in time: |
| 164 |
|
| 165 |
* Features will be added to the development main branch, to be released as |
| 166 |
Django 5.2. |
| 167 |
|
| 168 |
* Critical bug fixes will be applied to the ``stable/5.1.x`` branch, and |
| 169 |
released as 5.1.1, 5.1.2, etc. |
| 170 |
|
| 171 |
* Security fixes and bug fixes for data loss issues will be applied to |
| 172 |
``main`` and to the ``stable/5.1.x``, ``stable/5.0.x``, and |
| 173 |
``stable/4.2.x`` (LTS) branches. They will trigger the release of ``5.1.1``, |
| 174 |
``5.0.5``, ``4.2.8``, etc. |
| 175 |
|
| 176 |
* Documentation fixes will be applied to main, and, if easily backported, to |
| 177 |
the latest stable branch, ``5.1.x``. |
| 178 |
|
| 179 |
.. _release-process: |
| 180 |
|
| 181 |
Release process |
| 182 |
=============== |
| 183 |
|
| 184 |
Django uses a time-based release schedule, with feature releases every eight |
| 185 |
months or so. |
| 186 |
|
| 187 |
After each feature release, the release manager will publish a timeline for the |
| 188 |
next feature release. The timeline for an upcoming feature release can be found |
| 189 |
in the corresponding wiki roadmap page, e.g. |
| 190 |
https://code.djangoproject.com/wiki/Version6.0Roadmap. |
| 191 |
|
| 192 |
Feature release schedule and stages |
| 193 |
----------------------------------- |
| 194 |
|
| 195 |
Active development / Pre-feature freeze |
| 196 |
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
| 197 |
|
| 198 |
Work begins on the feature release ``A.B`` after the feature freeze of the |
| 199 |
previous release, i.e. when the ``stable/A.B-1.x`` branch is forked. |
| 200 |
|
| 201 |
You can find the current branch under active development in the |
| 202 |
`Django release process |
| 203 |
<https://code.djangoproject.com/#Djangoreleaseprocess>`_ on Trac. |
| 204 |
|
| 205 |
Feature freeze / Alpha release |
| 206 |
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
| 207 |
|
| 208 |
All major and minor features, including deprecations and breaking changes, must |
| 209 |
be merged by the feature freeze. Any features not done by this point will be |
| 210 |
deferred to the next feature release. |
| 211 |
|
| 212 |
At this point, the ``stable/A.B.x`` branch will be forked from ``main``. |
| 213 |
|
| 214 |
Non-release blocking bug fix freeze / Beta release |
| 215 |
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
| 216 |
|
| 217 |
After the alpha, all bug fixes merged in ``main`` are also backported to |
| 218 |
``stable/A.B.x``. Refactors are backported at the discretion of the merger. |
| 219 |
Mergers will be more and more conservative with backports, to avoid introducing |
| 220 |
regressions. |
| 221 |
|
| 222 |
In parallel to this phase, ``main`` can continue to receive new features, to be |
| 223 |
released in the ``A.B+1`` cycle. |
| 224 |
|
| 225 |
Translation string freeze / Release candidate release |
| 226 |
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
| 227 |
|
| 228 |
If there is still a consistent stream of release blockers coming in at the |
| 229 |
planned release candidate date, a beta 2 will be released to encourage further |
| 230 |
testing and the release candidate date will be pushed out ~1 month. |
| 231 |
|
| 232 |
The release candidate marks the string freeze, and it happens at least two |
| 233 |
weeks before the final release. Translators can then submit updated |
| 234 |
translations for inclusion in the final release. After this point, new |
| 235 |
translatable strings must not be added. |
| 236 |
|
| 237 |
After the release candidate, only release blockers and documentation fixes are |
| 238 |
backported. |
| 239 |
|
| 240 |
Final release |
| 241 |
~~~~~~~~~~~~~ |
| 242 |
|
| 243 |
Ideally, the final release will ship two weeks after the last release |
| 244 |
candidate. |
| 245 |
|
| 246 |
If there are major bugs still being found 2 weeks after the release candidate, |
| 247 |
there will be a decision on how to proceed (likely another release candidate |
| 248 |
would be issued and the final release date will be pushed out). |
| 249 |
|
| 250 |
Bug-fix releases |
| 251 |
---------------- |
| 252 |
|
| 253 |
After a feature release (e.g. A.B), the previous release will go into bugfix |
| 254 |
mode. |
| 255 |
|
| 256 |
The branch for the previous feature release (e.g. ``stable/A.B-1.x``) will |
| 257 |
include bugfixes. Critical bugs fixed on main must *also* be fixed on the |
| 258 |
bugfix branch; this means that commits need to cleanly separate bug fixes from |
| 259 |
feature additions. The developer who commits a fix to main will be |
| 260 |
responsible for also applying the fix to the current bugfix branch. |