Debian Codegraph @

docs/internals/release-process.txt

raw
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.