Debian Codegraph @

docs/internals/howto-release-django.txt

raw
1 =====================
2 How to release Django
3 =====================
4
5 This document explains how to release Django.
6
7 **Please, keep these instructions up-to-date if you make changes!** The point
8 here is to be descriptive, not prescriptive, so feel free to streamline or
9 otherwise make changes, but **update this document accordingly!**
10
11 Overview
12 ========
13
14 There are three types of releases that you might need to make:
15
16 * Security releases: disclosing and fixing a vulnerability. This'll
17 generally involve two or three simultaneous releases -- e.g.
18 3.2.x, 4.0.x, and, depending on timing, perhaps a 4.1.x.
19
20 * Regular version releases: either a final release (e.g. 4.1) or a
21 bugfix update (e.g. 4.1.1).
22
23 * Pre-releases: e.g. 4.2 alpha, beta, or rc.
24
25 The short version of the steps involved is:
26
27 #. If this is a security release, pre-notify the security distribution list
28 one week before the actual release.
29
30 #. Proofread the release notes, looking for organization and writing errors.
31 Draft a blog post and email announcement.
32
33 #. Update version numbers and create the release artifacts.
34
35 #. Create the new ``Release`` in the admin on ``djangoproject.com``.
36
37 #. Set the proper date but ensure the flag ``is_active`` is disabled.
38 #. Upload the artifacts (tarball, wheel, and checksums).
39
40 #. Verify package(s) signatures, check if they can be installed, and ensure
41 minimal functionality.
42
43 #. Upload the new version(s) to PyPI.
44
45 #. Enable the ``is_active`` flag for each release in the admin on
46 ``djangoproject.com``.
47
48 #. Post the blog entry and send out the email announcements.
49
50 #. Update version numbers post-release in stable branch(es).
51
52 #. Add stub release notes for the next patch release in ``main`` and backport.
53
54 There are a lot of details, so please read on.
55
56 Prerequisites
57 =============
58
59 You'll need a few things before getting started. If this is your first release,
60 you'll need to coordinate with another releaser to get all these things lined
61 up, and write to the Ops mailing list requesting the required access and
62 permissions.
63
64 * A Unix environment with these tools installed (in alphabetical order):
65
66 * bash
67 * git
68 * GPG
69 * make
70 * man
71 * hashing tools (typically ``md5sum``, ``sha1sum``, and ``sha256sum`` on
72 Linux, or ``md5`` and ``shasum`` on macOS)
73 * python
74
75 * A GPG key pair. Ensure that the private part of this key is securely stored.
76 The public part needs to be uploaded to your GitHub account, and also to the
77 Jenkins server running the "confirm release" job.
78
79 .. admonition:: More than one GPG key
80
81 If the key you want to use is not your default signing key, you'll need to
82 add ``-u [email protected]`` to every GPG signing command shown below, where
83 ``[email protected]`` is the email address associated with the key you want
84 to use.
85
86 * A clean Python virtual environment (Python 3.9+) to build artifacts, with
87 these required Python packages installed:
88
89 .. code-block:: shell
90
91 $ python -m pip install build twine
92
93 * Access to `Django's project on PyPI <https://pypi.org/project/Django/>`_ to
94 upload binaries, ideally with extra permissions to `yank a release
95 <https://pypi.org/help/#yanked>`_ if necessary. Create a project-scoped token
96 following the `official documentation <https://pypi.org/help/#apitoken>`_
97 and set up your ``$HOME/.pypirc`` file like this:
98
99 .. code-block:: ini
100 :caption: ``~/.pypirc``
101
102 [distutils]
103 index-servers =
104 pypi
105 django
106
107 [pypi]
108 username = __token__
109 password = # User-scoped or project-scoped token, to set as the default.
110
111 [django]
112 repository = https://upload.pypi.org/legacy/
113 username = __token__
114 password = # A project token.
115
116 * Access to `Django's project on Transifex
117 <https://app.transifex.com/django/django/>`_, with a Manager role. Generate
118 an API Token in the `user setting section
119 <https://app.transifex.com/user/settings/api/>`_ and set up your
120 ``$HOME/.transifexrc`` file like this:
121
122 .. code-block:: ini
123 :caption: ``~/.transifexrc``
124
125 [https://www.transifex.com]
126 rest_hostname = https://rest.api.transifex.com
127 token = # API token
128
129 * Access to the Django admin on ``djangoproject.com`` as a "Site maintainer".
130
131 * Access to create a post in the `Django Forum - Announcements category
132 <https://forum.djangoproject.com/c/announcements/7>`_ and to send emails to
133 the `django-announce <https://groups.google.com/g/django-announce/>`_
134 mailing list.
135
136 * Access to the ``django-security`` repo in GitHub. Among other things, this
137 provides access to the pre-notification distribution list (needed for
138 security release preparation tasks).
139
140 * Access to the Django project on `Read the Docs
141 <https://readthedocs.org/projects/django/>`_.
142
143 Pre-release tasks
144 =================
145
146 A few items need to be taken care of before even beginning the release process.
147 This stuff starts about a week before the release; most of it can be done
148 any time leading up to the actual release.
149
150 10 (or more) days before a security release
151 -------------------------------------------
152
153 #. Request the `CVE IDs <https://cveform.mitre.org/>`_ for the security
154 issue(s) being released. One CVE ID per issue, requested with
155 ``Vendor: djangoproject`` and ``Product: django``.
156
157 #. Generate the relevant (private) patch(es) using ``git format-patch``, one
158 for the ``main`` branch and one for each stable branch being patched.
159
160 A week before a security release
161 --------------------------------
162
163 #. Send out pre-notification exactly **one week** before the security release.
164 The template for that email and a list of the recipients are in the private
165 ``django-security`` GitHub wiki. BCC the pre-notification recipients and be
166 sure to include the relevant CVE IDs. Attach all the relevant patches
167 (targeting ``main`` and the stable branches) and sign the email text with
168 the key you'll use for the release, with a command like:
169
170 .. code-block:: shell
171
172 $ gpg --clearsign --digest-algo SHA256 prenotification-email.txt
173
174 #. :ref:`Notify django-announce <security-disclosure>` of the upcoming
175 security release with a general message such as:
176
177 .. code-block:: text
178
179 Notice of upcoming Django security releases (3.2.24, 4.2.10 and 5.0.2)
180
181 Django versions 5.0.2, 4.2.10, and 3.2.24 will be released on Tuesday,
182 February 6th, 2024 around 1500 UTC. They will fix one security defect
183 with severity "moderate".
184
185 For details of severity levels, see:
186 https://docs.djangoproject.com/en/dev/internals/security/#how-django-discloses-security-issues
187
188 A few days before any release
189 -----------------------------
190
191 #. As the release approaches, watch Trac to make sure no release blockers are
192 left for the upcoming release. Under exceptional circumstances, such as to
193 meet a pre-determined security release date, a release could still go ahead
194 with an open release blocker. The releaser is trusted with the decision to
195 release with an open release blocker or to postpone the release date of a
196 non-security release if required.
197
198 #. Check with the other mergers to make sure they don't have any uncommitted
199 changes for the release.
200
201 #. Proofread the release notes, including looking at the online version to
202 :ref:`catch any broken links <documentation-link-check>` or reST errors, and
203 make sure the release notes contain the correct date.
204
205 #. Double-check that the release notes mention deprecation timelines
206 for any APIs noted as deprecated, and that they mention any changes
207 in Python version support.
208
209 #. Double-check that the release notes index has a link to the notes
210 for the new release; this will be in ``docs/releases/index.txt``.
211
212 #. If this is a :term:`feature release`, ensure translations from Transifex
213 have been integrated. This is typically done by a separate translation's
214 manager rather than the releaser, but here are the steps. This process is a
215 bit lengthy so be sure to set aside 4-10 hours to do this, and ideally plan
216 for this task one or two days ahead of the release day.
217
218 In addition to having a configured Transifex account, the
219 `tx CLI <https://developers.transifex.com/docs/cli>`_ should be available in
220 your ``PATH``. Then, you can fetch all the translations by running:
221
222 .. code-block:: shell
223
224 $ python scripts/manage_translations.py fetch
225
226 This command takes some time to run. When done, carefully inspect the output
227 for potential errors and/or warnings. If there are some, you will need to
228 debug and resolve them on a case by case basis.
229
230 The recently fetched translations need some manual adjusting. First of all,
231 the ``PO-Revision-Date`` values must be manually bumped to be later than
232 ``POT-Creation-Date``. You can use a command similar to this to bulk update
233 all the ``.po`` files (compare the diff against the relevant stable branch):
234
235 .. code-block:: shell
236
237 $ git diff --name-only stable/5.0.x | grep "\.po" | xargs sed -ri "s/PO-Revision-Date: [0-9\-]+ /PO-Revision-Date: $(date -I) /g"
238
239 All the new ``.po`` files should be manually and carefully inspected to
240 avoid committing a change in a file without any new translations. Also,
241 there shouldn't be any changes in the "plural forms": if there are any
242 (usually Spanish and French report changes for this) those will need
243 reverting.
244
245 Lastly, commit the changed/added files (both ``.po`` and ``.mo``) and create
246 a new PR targeting the stable branch of the corresponding release (example
247 `PR updating translations for 4.2
248 <https://github.com/django/django/pull/16715>`_).
249
250 #. :ref:`Update the django-admin manual page <django-admin-manpage>`:
251
252 .. code-block:: shell
253
254 $ cd docs
255 $ make man
256 $ man _build/man/django-admin.1 # do a quick sanity check
257 $ cp _build/man/django-admin.1 man/django-admin.1
258
259 and then commit the changed man page.
260
261 #. If this is the "dot zero" release of a new series, create a new branch from
262 the current stable branch in the `django-docs-translations
263 <https://github.com/django/django-docs-translations>`_ repository. For
264 example, when releasing Django 4.2:
265
266 .. code-block:: shell
267
268 $ git checkout -b stable/4.2.x origin/stable/4.1.x
269 $ git push origin stable/4.2.x:stable/4.2.x
270
271 #. Write the announcement blog post for the release. You can enter it into the
272 admin at any time and mark it as inactive. Here are a few examples: `example
273 security release announcement`__, `example regular release announcement`__,
274 `example pre-release announcement`__.
275
276 __ https://www.djangoproject.com/weblog/2013/feb/19/security/
277 __ https://www.djangoproject.com/weblog/2012/mar/23/14/
278 __ https://www.djangoproject.com/weblog/2012/nov/27/15-beta-1/
279
280 A few days before a feature freeze
281 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
282
283 In preparation for the alpha release, the directory
284 ``/home/www/www/media/releases/A.B`` must be created on the djangoproject
285 server.
286
287 Before the feature freeze, a branch targeting ``main`` must be created to
288 prepare for the next feature release. It should be reviewed and approved a few
289 days before the freeze, allowing it to be merged after the stable branch is
290 cut. The following items should be addressed in this branch:
291
292 #. Update the ``VERSION`` tuple in ``django/__init__.py``, incrementing to the
293 next expected release (:commit:`example commit
294 <96700c7b378c592f0b1732302c22af2fd2c87fc6>`).
295
296 #. Create a stub release note for the next feature release. Use the stub from
297 the previous feature release or copy the contents from the current version
298 and delete most of the contents leaving only the headings
299 (:commit:`example commit <9b5ad4056ccf9ff7ea548f72d28eb66c1b4f84cc>`).
300
301 #. Remove ``.. versionadded::`` and ``.. versionchanged::`` annotations in the
302 documentation from two releases ago, as well as any remaining older
303 annotations. For example, in Django 5.1, notes for 4.2 will be removed
304 (:commit:`example commit <9edb7833b89e811eefd94974fb987f4605b0c0d7>`).
305
306 #. Remove features that have reached the end of their deprecation cycle,
307 including their docs and the ``.. deprecated::`` annotation. Each removal
308 should be done in a separate commit for clarity. In the commit message, add
309 a ``Refs #XXXXX --`` prefix linking to the original ticket where the
310 deprecation began if possible. Make sure this gets noted in the removed
311 features section in the release notes (:commit:`example commit
312 <f2d9c76aa7096ef3eed675b9eb824858f9dd81e5>`).
313
314 #. Increase the default PBKDF2 iterations in
315 ``django.contrib.auth.hashers.PBKDF2PasswordHasher`` by about 20%
316 (pick a round number). Run the tests, and update the 3 failing
317 hasher tests with the new values. Make sure this gets noted in the
318 release notes (:commit:`example commit
319 <7288866da4dddf3705148c703421858ec19cdb78>`).
320
321 Concrete examples for past feature release bootstrap branches: `5.2 bootstrap
322 <https://github.com/django/django/pull/18127>`_, `5.1 bootstrap
323 <https://github.com/django/django/pull/17246>`_, `5.0 bootstrap
324 <https://github.com/django/django/pull/16432>`_.
325
326 Feature freeze tasks
327 ====================
328
329 #. Remove empty sections from the release notes (:commit:`example commit
330 <9e6e58bad237a80ddd5e3ab8b834cecdaad8455e>`).
331
332 #. Build the release notes locally and read them. Make any necessary change
333 to improve flow or fix grammar (:commit:`example commit
334 <435bdab93889dae01e71c79598edab10627cc1f9>`).
335
336 #. Create a new stable branch from ``main``. For example, when feature freezing
337 Django 5.2:
338
339 .. code-block:: shell
340
341 $ git checkout -b stable/5.2.x upstream/main
342 $ git push upstream -u stable/5.2.x:stable/5.2.x
343
344 At the same time, update the ``django_next_version`` variable in
345 ``docs/conf.py`` on the stable release branch to point to the new
346 development version. For example, when creating ``stable/5.2.x``, set
347 ``django_next_version`` to ``'6.0'`` on the new stable branch
348 (:commit:`example commit <1eb62e5b622ef7fd6e0123d8bbf6662d893d5d08>`).
349
350 #. Go to the `Add release page in the admin`__, create a ``Release`` object for
351 the *final* release, ensuring that the *Release date* field is blank, thus
352 marking it as *unreleased*. For example, when creating ``stable/5.2.x``,
353 create ``5.2`` with the Release date field blank. If the release is part of
354 an LTS branch, mark it so.
355
356 __ https://www.djangoproject.com/admin/releases/release/add/
357
358 #. Go to the `Add document release page in the admin`__, create a new
359 ``DocumentRelease`` object for the English language for the newly created
360 ``Release`` object. Do not mark this as default.
361
362 __ https://www.djangoproject.com/admin/docs/documentrelease/add/
363
364 #. Add the new branch to `Read the Docs
365 <https://readthedocs.org/projects/django/>`_. Since the automatically
366 generated version names ("stable-A.B.x") differ from the version names
367 used in Read the Docs ("A.B.x"), `create a ticket
368 <https://github.com/readthedocs/readthedocs.org/issues/5537>`_ requesting
369 the new version.
370
371 #. `Request the new classifier on PyPI
372 <https://github.com/pypa/trove-classifiers/issues/29>`_. For example
373 ``Framework :: Django :: 5.2``.
374
375 #. Create a `roadmap page
376 <https://code.djangoproject.com/wiki/Version6.0Roadmap>`_ for the next
377 release on Trac. To create a new page on the Wiki, navigate to the URL of
378 where you wish to create the page and a "Create this page" button will be
379 available.
380
381 #. Update the current branch under active development and add pre-release
382 branch in the `Django release process
383 <https://code.djangoproject.com/#Djangoreleaseprocess>`_ on Trac.
384
385 #. Update the ``docs/fixtures/doc_releases.json`` JSON fixture for
386 djangoproject.com, so people without access to the production DB can still
387 run an up-to-date copy of the docs site
388 (`example PR <https://github.com/django/djangoproject.com/pull/1446>`__).
389 This will be merged after the final release.
390
391 Actually rolling the release
392 ============================
393
394 OK, this is the fun part, where we actually push out a release! If you're
395 issuing **multiple releases**, repeat these steps for each release.
396
397 #. Check `Jenkins`__ is green for the version(s) you're putting out. You
398 probably shouldn't issue a release until it's green, and you should make
399 sure that the latest green run includes the changes that you are releasing.
400
401 __ https://djangoci.com
402
403 #. Cleanup the release notes for this release. Make these changes in ``main``
404 and backport to all branches where the release notes for a particular
405 version are located.
406
407 #. For a feature release, remove the ``UNDER DEVELOPMENT`` header at the top
408 of the release notes, remove the ``Expected`` prefix and update the
409 release date, if necessary (:commit:`example commit
410 <1994a2643881a9e3f9fa8d3e0794c1a9933a1831>`).
411
412 #. For a patch release, remove the ``Expected`` prefix and update the
413 release date for all releases, if necessary (:commit:`example commit
414 <34a503162fe222033a1cd3249bccad014fcd1d20>`).
415
416 #. A release always begins from a release branch, so you should make sure
417 you're on an up-to-date stable branch. Also, you should have available a
418 clean and dedicated virtual environment per version being released. For
419 example:
420
421 .. code-block:: shell
422
423 $ git checkout stable/4.1.x
424 $ git pull
425
426 #. If this is a security release, merge the appropriate patches from
427 ``django-security``. Rebase these patches as necessary to make each one a
428 plain commit on the release branch rather than a merge commit. To ensure
429 this, merge them with the ``--ff-only`` flag; for example:
430
431 .. code-block:: shell
432
433 $ git checkout stable/4.1.x
434 $ git merge --ff-only security/4.1.x
435
436 (This assumes ``security/4.1.x`` is a branch in the ``django-security`` repo
437 containing the necessary security patches for the next release in the 4.1
438 series.)
439
440 If git refuses to merge with ``--ff-only``, switch to the security-patch
441 branch and rebase it on the branch you are about to merge it into (``git
442 checkout security/4.1.x; git rebase stable/4.1.x``) and then switch back and
443 do the merge. Make sure the commit message for each security fix explains
444 that the commit is a security fix and that an announcement will follow
445 (:commit:`example security commit <bf39978a53f117ca02e9a0c78b76664a41a54745>`).
446
447 #. Update the version number in ``django/__init__.py`` for the release.
448 Please see `notes on setting the VERSION tuple`_ below for details
449 on ``VERSION`` (:commit:`example commit
450 <2719a7f8c161233f45d34b624a9df9392c86cc1b>`).
451
452 #. If this is a pre-release package also update the "Development Status"
453 trove classifier in ``pyproject.toml`` to reflect this. An ``rc``
454 pre-release should not change the trove classifier (:commit:`example
455 commit for alpha release <759921c8e9ad151932fc913ab429fef0a6112ef8>`,
456 :commit:`example commit for beta release
457 <25fec8940b24107e21314ab6616e18ce8dec1c1c>`).
458
459 #. Otherwise, make sure the classifier is set to
460 ``Development Status :: 5 - Production/Stable``.
461
462 Building the artifacts
463 ----------------------
464
465 .. admonition:: Optionally use helper scripts
466
467 You can streamline some of the steps below using helper scripts from the
468 ``scripts`` folder:
469
470 * Release script example run:
471
472 .. code-block:: shell
473
474 $ PGP_KEY_ID=<key-id> PGP_KEY_URL=<key-url> DEST_FOLDER=~/releases scripts/do_django_release.py
475
476 * Verify the release (after artifacts were uploaded):
477
478 .. code-block:: shell
479
480 $ VERSION=5.2.1 scripts/verify_release.sh
481
482 #. Tag the release using ``git tag``. For example:
483
484 .. code-block:: shell
485
486 $ git tag --sign --message="Tag 4.1.1" 4.1.1
487
488 You can check your work running ``git tag --verify <tag>``.
489
490 #. Make sure you have an absolutely clean tree by running ``git clean -dfx``.
491
492 #. Run ``python -m build`` to generate the release packages. This will create
493 the release artifacts (tarball and wheel) in a ``dist/`` directory. For
494 Django 5.0 or older, you need to run ``make -f extras/Makefile`` instead.
495
496 #. Generate the hashes of the release packages:
497
498 .. code-block:: shell
499
500 $ cd dist
501 $ md5sum *
502 $ sha1sum *
503 $ sha256sum *
504
505 #. Create a "checksums" file, ``Django-<<VERSION>>.checksum.txt`` containing
506 the hashes and release information. Start with this template and insert the
507 correct version, date, GPG key ID (from
508 ``gpg --list-keys --keyid-format LONG``), release manager's GitHub username,
509 release URL, and checksums:
510
511 .. code-block:: text
512
513 This file contains MD5, SHA1, and SHA256 checksums for the source-code
514 tarball and wheel files of Django <<VERSION>>, released <<DATE>>.
515
516 To use this file, you will need a working install of PGP or other
517 compatible public-key encryption software. You will also need to have
518 the Django release manager's public key in your keyring. This key has
519 the ID ``XXXXXXXXXXXXXXXX`` and can be imported from the MIT
520 keyserver, for example, if using the open-source GNU Privacy Guard
521 implementation of PGP:
522
523 gpg --keyserver pgp.mit.edu --recv-key XXXXXXXXXXXXXXXX
524
525 or via the GitHub API:
526
527 curl https://github.com/<<RELEASE MANAGER GITHUB USERNAME>>.gpg | gpg --import -
528
529 Once the key is imported, verify this file:
530
531 gpg --verify <<THIS FILENAME>>
532
533 Once you have verified this file, you can use normal MD5, SHA1, or SHA256
534 checksumming applications to generate the checksums of the Django
535 package and compare them to the checksums listed below.
536
537 Release packages
538 ================
539
540 https://www.djangoproject.com/download/<<VERSION>>/tarball/
541 https://www.djangoproject.com/download/<<VERSION>>/wheel/
542
543 MD5 checksums
544 =============
545
546 <<MD5SUM>> <<RELEASE TAR.GZ FILENAME>>
547 <<MD5SUM>> <<RELEASE WHL FILENAME>>
548
549 SHA1 checksums
550 ==============
551
552 <<SHA1SUM>> <<RELEASE TAR.GZ FILENAME>>
553 <<SHA1SUM>> <<RELEASE WHL FILENAME>>
554
555 SHA256 checksums
556 ================
557
558 <<SHA256SUM>> <<RELEASE TAR.GZ FILENAME>>
559 <<SHA256SUM>> <<RELEASE WHL FILENAME>>
560
561 #. Sign the checksum file (``gpg --clearsign --digest-algo SHA256
562 Django-<version>.checksum.txt``). This generates a signed document,
563 ``Django-<version>.checksum.txt.asc`` which you can then verify using ``gpg
564 --verify Django-<version>.checksum.txt.asc``.
565
566 Making the release(s) available to the public
567 =============================================
568
569 Now you're ready to actually put the release out there. To do this:
570
571 #. Create a new ``Release`` entry in the `djangoproject.com's admin
572 <https://www.djangoproject.com/admin/releases/release/add/>`_. If this is a
573 security release, this should be done 15 minutes before the announced
574 release time, no sooner:
575
576 Version
577 Must match the version number as defined in the tarball
578 (``django-<version>.tar.gz``). For example: "5.2", "4.1.1", or "4.2rc1".
579
580 Is active
581 Set to False until the release is fully published (last step).
582
583 LTS
584 Enable if the release is part of an :abbr:`LTS (Long Term Support)`
585 branch.
586
587 Dates
588 Set the release date to today. This release will not be published until
589 ``is_active`` is enabled.
590
591 Artifacts
592 Upload the tarball (``django-<version>.tar.gz``), wheel
593 (``django-<version>-py3-none-any.whl``), and checksum
594 (``django-<version>.checksum.txt.asc``) files created earlier.
595
596 #. Test that the release packages install correctly using ``pip``. Here's one
597 simple method (this just tests that the binaries are available, that they
598 install correctly, and that migrations and the development server start, but
599 it'll catch silly mistakes):
600 https://code.djangoproject.com/wiki/ReleaseTestNewVersion.
601
602 #. Run the `confirm-release`__ build on Jenkins to verify the checksum file(s)
603 (e.g. use ``4.2rc1`` for
604 https://media.djangoproject.com/pgp/Django-4.2rc1.checksum.txt).
605
606 __ https://djangoci.com/job/confirm-release/
607
608 #. Upload the release packages to PyPI (for pre-releases, only upload the wheel
609 file):
610
611 .. code-block:: shell
612
613 $ twine upload --repository django dist/*
614
615 #. Update the newly created ``Release`` in the admin in ``djangoproject.com``
616 and enable the ``is_active`` flag.
617
618 #. Push your work and the new tag:
619
620 .. code-block:: shell
621
622 $ git push
623 $ git push --tags
624
625 #. Make the blog post announcing the release live.
626
627 #. For a new version release (e.g. 4.1, 4.2), update the default stable version
628 of the docs by flipping the ``is_default`` flag to ``True`` on the
629 appropriate ``DocumentRelease`` object in the ``docs.djangoproject.com``
630 database (this will automatically flip it to ``False`` for all
631 others); you can do this using the site's admin.
632
633 Create new ``DocumentRelease`` objects for each language that has an entry
634 for the previous release. Update djangoproject.com's `robots.docs.txt`__
635 file by copying the result generated from running the command
636 ``manage_translations.py robots_txt`` in the current stable branch from the
637 `django-docs-translations repository`__. For example, when releasing Django
638 4.2:
639
640 .. code-block:: shell
641
642 $ git checkout stable/4.2.x
643 $ git pull
644 $ python manage_translations.py robots_txt
645
646 __ https://github.com/django/djangoproject.com/blob/main/djangoproject/static/robots.docs.txt
647 __ https://github.com/django/django-docs-translations
648
649 #. Post the release announcement to the |django-announce| mailing list and the
650 Django Forum. This should include a link to the announcement blog post.
651
652 #. If this is a security release, send a separate email to
653 [email protected]. Provide a descriptive subject, for example,
654 "Django" plus the issue title from the release notes (including CVE ID). The
655 message body should include the vulnerability details, for example, the
656 announcement blog post text. Include a link to the announcement blog post.
657
658 Post-release
659 ============
660
661 You're almost done! All that's left to do now is:
662
663 #. If this is not a pre-release, update the ``VERSION`` tuple in
664 ``django/__init__.py`` again, incrementing to whatever the next expected
665 release will be. For example, after releasing 4.1.1, update ``VERSION`` to
666 ``VERSION = (4, 1, 2, 'alpha', 0)`` (:commit:`example commit
667 <a4d19953d46247ee1992b3427fe652e941524272>`).
668
669 #. Add the release in `Trac's versions list`_ if necessary (and make it the
670 default by changing the ``default_version`` setting in the
671 code.djangoproject.com's `trac.ini`__, if it's a final release). The new X.Y
672 version should be added after the alpha release and the default version
673 should be updated after "dot zero" release.
674
675 __ https://github.com/django/code.djangoproject.com/blob/main/trac-env/conf/trac.ini
676
677 #. If this was a final release:
678
679 #. Update the current stable branch and remove the pre-release branch in the
680 `Django release process
681 <https://code.djangoproject.com/#Djangoreleaseprocess>`_ on Trac.
682
683 #. Update djangoproject.com's download page (`example PR
684 <https://github.com/django/djangoproject.com/pull/1444>`__).
685
686 #. If this was a security release, update :doc:`/releases/security` with
687 details of the issues addressed.
688
689 #. If this was a pre-release, the translation catalogs need to be updated:
690
691 #. Make a new branch from the recently released stable branch:
692
693 .. code-block:: shell
694
695 git checkout stable/A.B.x
696 git checkout -b update-translations-catalog-A.B.x
697
698 #. Ensure that the release's dedicated virtual environment is enabled and
699 run the following:
700
701 .. code-block:: shell
702
703 $ cd django
704 $ django-admin makemessages -l en --domain=djangojs --domain=django
705 processing locale en
706
707 #. Review the diff before pushing and avoid committing changes to the
708 ``.po`` files without any new translations (:commit:`example commit
709 <d2b1ec551567c208abfdd21b27ff6d08ae1a6371>`).
710
711 #. Make a pull request against the corresponding stable branch and merge
712 once approved.
713
714 #. Forward port the updated source translations to the ``main`` branch
715 (:commit:`example commit <aed303aff57ac990894b6354af001b0e8ea55f71>`).
716
717 #. If this was an ``rc`` pre-release, call for translations for the upcoming
718 release in the `Django Forum - Internationalization category
719 <https://forum.djangoproject.com/c/internals/i18n/14>`_.
720
721 .. _Trac's versions list: https://code.djangoproject.com/admin/ticket/versions
722
723 Notes on setting the VERSION tuple
724 ==================================
725
726 Django's version reporting is controlled by the ``VERSION`` tuple in
727 ``django/__init__.py``. This is a five-element tuple, whose elements
728 are:
729
730 #. Major version.
731 #. Minor version.
732 #. Micro version.
733 #. Status -- can be one of "alpha", "beta", "rc" or "final".
734 #. Series number, for alpha/beta/RC packages which run in sequence
735 (allowing, for example, "beta 1", "beta 2", etc.).
736
737 For a final release, the status is always "final" and the series
738 number is always 0. A series number of 0 with an "alpha" status will
739 be reported as "pre-alpha".
740
741 Some examples:
742
743 * ``(4, 1, 1, "final", 0)`` → "4.1.1"
744
745 * ``(4, 2, 0, "alpha", 0)`` → "4.2 pre-alpha"
746
747 * ``(4, 2, 0, "beta", 1)`` → "4.2 beta 1"