| 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" |