{"title":"How to release Django","version":"5.2","locale":"en","docname":"internals/howto-release-django","url":"/en/5.2/internals/howto-release-django/","canonical":"https://djangodocs.dev/en/5.2/internals/howto-release-django/","summary":"This document explains how to release Django. Please, keep these instructions up-to-date if you make changes!","html":"

How to release DjangoLink to this heading#

\n

This document explains how to release Django.

\n

Please, keep these instructions up-to-date if you make changes! The point\nhere is to be descriptive, not prescriptive, so feel free to streamline or\notherwise make changes, but update this document accordingly!

\n
\n

OverviewLink to this heading#

\n

There are three types of releases that you might need to make:

\n\n

The short version of the steps involved is:

\n
    \n

  1. If this is a security release, pre-notify the security distribution list\none week before the actual release.

    2. \n

  2. Proofread the release notes, looking for organization and writing errors.\nDraft a blog post and email announcement.

    3. \n

  3. Update version numbers and create the release artifacts.

    4. \n

  4. Create the new Release in the admin on djangoproject.com.

    \n
      \n

    1. Set the proper date but ensure the flag is_active is disabled.

      2. \n

    2. Upload the artifacts (tarball, wheel, and checksums).

      3. \n
    \n
    5. \n

  5. Verify package(s) signatures, check if they can be installed, and ensure\nminimal functionality.

    6. \n

  6. Upload the new version(s) to PyPI.

    7. \n

  7. Enable the is_active flag for each release in the admin on\ndjangoproject.com.

    8. \n

  8. Post the blog entry and send out the email announcements.

    9. \n

  9. Update version numbers post-release in stable branch(es).

    10. \n

  10. Add stub release notes for the next patch release in main and backport.

    11. \n
\n

There are a lot of details, so please read on.

\n
\n
\n

PrerequisitesLink to this heading#

\n

You’ll need a few things before getting started. If this is your first release,\nyou’ll need to coordinate with another releaser to get all these things lined\nup, and write to the Ops mailing list requesting the required access and\npermissions.

\n\n
\n
\n

Pre-release tasksLink to this heading#

\n

A few items need to be taken care of before even beginning the release process.\nThis stuff starts about a week before the release; most of it can be done\nany time leading up to the actual release.

\n
\n

10 (or more) days before a security releaseLink to this heading#

\n
    \n

  1. Request the CVE IDs for the security\nissue(s) being released. One CVE ID per issue, requested with\nVendor: djangoproject and Product: django.

    2. \n

  2. Generate the relevant (private) patch(es) using git format-patch, one\nfor the main branch and one for each stable branch being patched.

    3. \n
\n
\n
\n

A week before a security releaseLink to this heading#

\n
    \n

  1. Send out pre-notification exactly one week before the security release.\nThe template for that email and a list of the recipients are in the private\ndjango-security GitHub wiki. BCC the pre-notification recipients and be\nsure to include the relevant CVE IDs. Attach all the relevant patches\n(targeting main and the stable branches) and sign the email text with\nthe key you’ll use for the release, with a command like:

    \n
    Shell
    $ gpg --clearsign --digest-algo SHA256 prenotification-email.txt\n
    \n
    2. \n

  2. Notify django-announce of the upcoming\nsecurity release with a general message such as:

    \n
    Text
    Notice of upcoming Django security releases (3.2.24, 4.2.10 and 5.0.2)\n\nDjango versions 5.0.2, 4.2.10, and 3.2.24 will be released on Tuesday,\nFebruary 6th, 2024 around 1500 UTC. They will fix one security defect\nwith severity "moderate".\n\nFor details of severity levels, see:\nhttps://docs.djangoproject.com/en/dev/internals/security/#how-django-discloses-security-issues\n
    \n
    3. \n
\n
\n
\n

A few days before any releaseLink to this heading#

\n
    \n

  1. As the release approaches, watch Trac to make sure no release blockers are\nleft for the upcoming release. Under exceptional circumstances, such as to\nmeet a pre-determined security release date, a release could still go ahead\nwith an open release blocker. The releaser is trusted with the decision to\nrelease with an open release blocker or to postpone the release date of a\nnon-security release if required.

    2. \n

  2. Check with the other mergers to make sure they don’t have any uncommitted\nchanges for the release.

    3. \n

  3. Proofread the release notes, including looking at the online version to\ncatch any broken links or reST errors, and\nmake sure the release notes contain the correct date.

    4. \n

  4. Double-check that the release notes mention deprecation timelines\nfor any APIs noted as deprecated, and that they mention any changes\nin Python version support.

    5. \n

  5. Double-check that the release notes index has a link to the notes\nfor the new release; this will be in docs/releases/index.txt.

    6. \n

  6. If this is a feature release, ensure translations from Transifex\nhave been integrated. This is typically done by a separate translation’s\nmanager rather than the releaser, but here are the steps. This process is a\nbit lengthy so be sure to set aside 4-10 hours to do this, and ideally plan\nfor this task one or two days ahead of the release day.

    \n

    In addition to having a configured Transifex account, the\ntx CLI should be available in\nyour PATH. Then, you can fetch all the translations by running:

    \n
    Shell
    $ python scripts/manage_translations.py fetch\n
    \n

    This command takes some time to run. When done, carefully inspect the output\nfor potential errors and/or warnings. If there are some, you will need to\ndebug and resolve them on a case by case basis.

    \n

    The recently fetched translations need some manual adjusting. First of all,\nthe PO-Revision-Date values must be manually bumped to be later than\nPOT-Creation-Date. You can use a command similar to this to bulk update\nall the .po files (compare the diff against the relevant stable branch):

    \n
    Shell
    $ 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"\n
    \n

    All the new .po files should be manually and carefully inspected to\navoid committing a change in a file without any new translations. Also,\nthere shouldn’t be any changes in the “plural forms”: if there are any\n(usually Spanish and French report changes for this) those will need\nreverting.

    \n

    Lastly, commit the changed/added files (both .po and .mo) and create\na new PR targeting the stable branch of the corresponding release (example\nPR updating translations for 4.2).

    \n
    7. \n

  7. Update the django-admin manual page:

    \n
    Shell
    $ cd docs\n$ make man\n$ man _build/man/django-admin.1  # do a quick sanity check\n$ cp _build/man/django-admin.1 man/django-admin.1\n
    \n

    and then commit the changed man page.

    \n
    8. \n

  8. If this is the “dot zero” release of a new series, create a new branch from\nthe current stable branch in the django-docs-translations repository. For\nexample, when releasing Django 4.2:

    \n
    Shell
    $ git checkout -b stable/4.2.x origin/stable/4.1.x\n$ git push origin stable/4.2.x:stable/4.2.x\n
    \n
    9. \n

  9. Write the announcement blog post for the release. You can enter it into the\nadmin at any time and mark it as inactive. Here are a few examples: example\nsecurity release announcement, example regular release announcement,\nexample pre-release announcement.

    10. \n
\n
\n

A few days before a feature freezeLink to this heading#

\n

In preparation for the alpha release, the directory\n/home/www/www/media/releases/A.B must be created on the djangoproject\nserver.

\n

Before the feature freeze, a branch targeting main must be created to\nprepare for the next feature release. It should be reviewed and approved a few\ndays before the freeze, allowing it to be merged after the stable branch is\ncut. The following items should be addressed in this branch:

\n
    \n

  1. Update the VERSION tuple in django/__init__.py, incrementing to the\nnext expected release (example commit).

    2. \n

  2. Create a stub release note for the next feature release. Use the stub from\nthe previous feature release or copy the contents from the current version\nand delete most of the contents leaving only the headings\n(example commit).

    3. \n

  3. Remove .. versionadded:: and .. versionchanged:: annotations in the\ndocumentation from two releases ago, as well as any remaining older\nannotations. For example, in Django 5.1, notes for 4.2 will be removed\n(example commit).

    4. \n

  4. Remove features that have reached the end of their deprecation cycle,\nincluding their docs and the .. deprecated:: annotation. Each removal\nshould be done in a separate commit for clarity. In the commit message, add\na Refs #XXXXX -- prefix linking to the original ticket where the\ndeprecation began if possible. Make sure this gets noted in the removed\nfeatures section in the release notes (example commit).

    5. \n

  5. Increase the default PBKDF2 iterations in\ndjango.contrib.auth.hashers.PBKDF2PasswordHasher by about 20%\n(pick a round number). Run the tests, and update the 3 failing\nhasher tests with the new values. Make sure this gets noted in the\nrelease notes (example commit).

    6. \n
\n

Concrete examples for past feature release bootstrap branches: 5.2 bootstrap, 5.1 bootstrap, 5.0 bootstrap.

\n
\n
\n
\n
\n

Feature freeze tasksLink to this heading#

\n
    \n

  1. Remove empty sections from the release notes (example commit).

    2. \n

  2. Build the release notes locally and read them. Make any necessary change\nto improve flow or fix grammar (example commit).

    3. \n

  3. Create a new stable branch from main. For example, when feature freezing\nDjango 5.2:

    \n
    Shell
    $ git checkout -b stable/5.2.x upstream/main\n$ git push upstream -u stable/5.2.x:stable/5.2.x\n
    \n

    At the same time, update the django_next_version variable in\ndocs/conf.py on the stable release branch to point to the new\ndevelopment version. For example, when creating stable/5.2.x, set\ndjango_next_version to '6.0' on the new stable branch\n(example commit).

    \n
    4. \n

  4. Go to the Add release page in the admin, create a Release object for\nthe final release, ensuring that the Release date field is blank, thus\nmarking it as unreleased. For example, when creating stable/5.2.x,\ncreate 5.2 with the Release date field blank. If the release is part of\nan LTS branch, mark it so.

    \n
    5. \n

  5. Go to the Add document release page in the admin, create a new\nDocumentRelease object for the English language for the newly created\nRelease object. Do not mark this as default.

    \n
    6. \n

  6. Add the new branch to Read the Docs. Since the automatically\ngenerated version names (“stable-A.B.x”) differ from the version names\nused in Read the Docs (“A.B.x”), create a ticket requesting\nthe new version.

    7. \n

  7. Request the new classifier on PyPI. For example\nFramework :: Django :: 5.2.

    8. \n

  8. Create a roadmap page for the next\nrelease on Trac. To create a new page on the Wiki, navigate to the URL of\nwhere you wish to create the page and a “Create this page” button will be\navailable.

    9. \n

  9. Update the current branch under active development and add pre-release\nbranch in the Django release process on Trac.

    10. \n

  10. Update the docs/fixtures/doc_releases.json JSON fixture for\ndjangoproject.com, so people without access to the production DB can still\nrun an up-to-date copy of the docs site\n(example PR).\nThis will be merged after the final release.

    11. \n
\n
\n
\n

Actually rolling the releaseLink to this heading#

\n

OK, this is the fun part, where we actually push out a release! If you’re\nissuing multiple releases, repeat these steps for each release.

\n
    \n

  1. Check Jenkins is green for the version(s) you’re putting out. You\nprobably shouldn’t issue a release until it’s green, and you should make\nsure that the latest green run includes the changes that you are releasing.

    \n
    2. \n

  2. Cleanup the release notes for this release. Make these changes in main\nand backport to all branches where the release notes for a particular\nversion are located.

    \n
      \n

    1. For a feature release, remove the UNDER DEVELOPMENT header at the top\nof the release notes, remove the Expected prefix and update the\nrelease date, if necessary (example commit).

      2. \n

    2. For a patch release, remove the Expected prefix and update the\nrelease date for all releases, if necessary (example commit).

      3. \n
    \n
    3. \n

  3. A release always begins from a release branch, so you should make sure\nyou’re on an up-to-date stable branch. Also, you should have available a\nclean and dedicated virtual environment per version being released. For\nexample:

    \n
    Shell
    $ git checkout stable/4.1.x\n$ git pull\n
    \n
    4. \n

  4. If this is a security release, merge the appropriate patches from\ndjango-security. Rebase these patches as necessary to make each one a\nplain commit on the release branch rather than a merge commit. To ensure\nthis, merge them with the --ff-only flag; for example:

    \n
    Shell
    $ git checkout stable/4.1.x\n$ git merge --ff-only security/4.1.x\n
    \n

    (This assumes security/4.1.x is a branch in the django-security repo\ncontaining the necessary security patches for the next release in the 4.1\nseries.)

    \n

    If git refuses to merge with --ff-only, switch to the security-patch\nbranch and rebase it on the branch you are about to merge it into (git\ncheckout security/4.1.x; git rebase stable/4.1.x) and then switch back and\ndo the merge. Make sure the commit message for each security fix explains\nthat the commit is a security fix and that an announcement will follow\n(example security commit).

    \n
    5. \n

  5. Update the version number in django/__init__.py for the release.\nPlease see notes on setting the VERSION tuple below for details\non VERSION (example commit).

    \n
      \n

    1. If this is a pre-release package also update the “Development Status”\ntrove classifier in pyproject.toml to reflect this. An rc\npre-release should not change the trove classifier (example\ncommit for alpha release,\nexample commit for beta release).

      2. \n

    2. Otherwise, make sure the classifier is set to\nDevelopment Status :: 5 - Production/Stable.

      3. \n
    \n
    6. \n
\n
\n

Building the artifactsLink to this heading#

\n\n
    \n

  1. Tag the release using git tag. For example:

    \n
    Shell
    $ git tag --sign --message="Tag 4.1.1" 4.1.1\n
    \n

    You can check your work running git tag --verify <tag>.

    \n
    2. \n

  2. Make sure you have an absolutely clean tree by running git clean -dfx.

    3. \n

  3. Run python -m build to generate the release packages. This will create\nthe release artifacts (tarball and wheel) in a dist/ directory. For\nDjango 5.0 or older, you need to run make -f extras/Makefile instead.

    4. \n

  4. Generate the hashes of the release packages:

    \n
    Shell
    $ cd dist\n$ md5sum *\n$ sha1sum *\n$ sha256sum *\n
    \n
    5. \n

  5. Create a “checksums” file, Django-<<VERSION>>.checksum.txt containing\nthe hashes and release information. Start with this template and insert the\ncorrect version, date, GPG key ID (from\ngpg --list-keys --keyid-format LONG), release manager’s GitHub username,\nrelease URL, and checksums:

    \n
    Text
    This file contains MD5, SHA1, and SHA256 checksums for the source-code\ntarball and wheel files of Django <<VERSION>>, released <<DATE>>.\n\nTo use this file, you will need a working install of PGP or other\ncompatible public-key encryption software. You will also need to have\nthe Django release manager's public key in your keyring. This key has\nthe ID ``XXXXXXXXXXXXXXXX`` and can be imported from GitHub, for example,\nif using the open-source GNU Privacy Guard implementation of PGP:\n\n    curl https://github.com/<<RELEASE MANAGER GITHUB USERNAME>>.gpg | gpg --import -\n\nOnce the key is imported, verify this file:\n\n    gpg --verify <<THIS FILENAME>>\n\nOnce you have verified this file, you can use normal MD5, SHA1, or SHA256\nchecksumming applications to generate the checksums of the Django\npackage and compare them to the checksums listed below.\n\nRelease packages\n================\n\nhttps://www.djangoproject.com/download/<<VERSION>>/tarball/\nhttps://www.djangoproject.com/download/<<VERSION>>/wheel/\n\nMD5 checksums\n=============\n\n<<MD5SUM>>  <<RELEASE TAR.GZ FILENAME>>\n<<MD5SUM>>  <<RELEASE WHL FILENAME>>\n\nSHA1 checksums\n==============\n\n<<SHA1SUM>>  <<RELEASE TAR.GZ FILENAME>>\n<<SHA1SUM>>  <<RELEASE WHL FILENAME>>\n\nSHA256 checksums\n================\n\n<<SHA256SUM>>  <<RELEASE TAR.GZ FILENAME>>\n<<SHA256SUM>>  <<RELEASE WHL FILENAME>>\n
    \n
    6. \n

  6. Sign the checksum file (gpg --clearsign --digest-algo SHA256\nDjango-<version>.checksum.txt). This generates a signed document,\nDjango-<version>.checksum.txt.asc which you can then verify using gpg\n--verify Django-<version>.checksum.txt.asc.

    7. \n
\n
\n
\n
\n

Making the release(s) available to the publicLink to this heading#

\n

Now you’re ready to actually put the release out there. To do this:

\n
    \n

  1. Create a new Release entry in the djangoproject.com’s admin. If this is a\nsecurity release, this should be done 15 minutes before the announced\nrelease time, no sooner:

    \n
    \n
    Version

    Must match the version number as defined in the tarball\n(django-<version>.tar.gz). For example: “5.2”, “4.1.1”, or “4.2rc1”.

    \n
    \n
    Is active

    Set to False until the release is fully published (last step).

    \n
    \n
    LTS

    Enable if the release is part of an LTS\nbranch.

    \n
    \n
    Dates

    Set the release date to today. This release will not be published until\nis_active is enabled.

    \n
    \n
    Artifacts

    Upload the tarball (django-<version>.tar.gz), wheel\n(django-<version>-py3-none-any.whl), and checksum\n(django-<version>.checksum.txt.asc) files created earlier.

    \n
    \n
    \n
    2. \n

  2. Test that the release packages install correctly using pip. Here’s one\nsimple method (this just tests that the binaries are available, that they\ninstall correctly, and that migrations and the development server start, but\nit’ll catch silly mistakes):\nhttps://code.djangoproject.com/wiki/ReleaseTestNewVersion.

    3. \n

  3. Run the confirm-release build on Jenkins to verify the checksum file(s)\n(e.g. use 4.2rc1 for\nhttps://media.djangoproject.com/pgp/Django-4.2rc1.checksum.txt).

    \n
    4. \n

  4. Upload the release packages to PyPI (for pre-releases, only upload the wheel\nfile):

    \n
    Shell
    $ twine upload --repository django dist/*\n
    \n
    5. \n

  5. Update the newly created Release in the admin in djangoproject.com\nand enable the is_active flag.

    6. \n

  6. Push your work and the new tag:

    \n
    Shell
    $ git push\n$ git push --tags\n
    \n
    7. \n

  7. Make the blog post announcing the release live.

    8. \n

  8. For a new version release (e.g. 4.1, 4.2), update the default stable version\nof the docs by flipping the is_default flag to True on the\nappropriate DocumentRelease object in the docs.djangoproject.com\ndatabase (this will automatically flip it to False for all\nothers); you can do this using the site’s admin.

    \n

    Create new DocumentRelease objects for each language that has an entry\nfor the previous release. Update djangoproject.com’s robots.docs.txt\nfile by copying the result generated from running the command\nmanage_translations.py robots_txt in the current stable branch from the\ndjango-docs-translations repository. For example, when releasing Django\n4.2:

    \n
    Shell
    $ git checkout stable/4.2.x\n$ git pull\n$ python manage_translations.py robots_txt\n
    \n
    9. \n

  9. Post the release announcement to the django-announce mailing list and the\nDjango Forum. This should include a link to the announcement blog post.

    10. \n

  10. If this is a security release, send a separate email to\noss-security@lists.openwall.com. Provide a descriptive subject, for example,\n“Django” plus the issue title from the release notes (including CVE ID). The\nmessage body should include the vulnerability details, for example, the\nannouncement blog post text. Include a link to the announcement blog post.

    11. \n
\n
\n
\n

Post-releaseLink to this heading#

\n

You’re almost done! All that’s left to do now is:

\n
    \n

  1. If this is not a pre-release, update the VERSION tuple in\ndjango/__init__.py again, incrementing to whatever the next expected\nrelease will be. For example, after releasing 4.1.1, update VERSION to\nVERSION = (4, 1, 2, 'alpha', 0) (example commit).

    2. \n

  2. Add the release in Trac’s versions list if necessary (and make it the\ndefault by changing the default_version setting in the\ncode.djangoproject.com’s trac.ini, if it’s a final release). The new X.Y\nversion should be added after the alpha release and the default version\nshould be updated after “dot zero” release.

    \n
    3. \n

  3. If this was a final release:

    \n
      \n

    1. Update the current stable branch and remove the pre-release branch in the\nDjango release process on Trac.

      2. \n

    2. Update djangoproject.com’s download page (example PR).

      3. \n
    \n
    4. \n

  4. If this was a security release, update Archive of security issues with\ndetails of the issues addressed.

    5. \n

  5. If this was a pre-release, the translation catalogs need to be updated:

    \n
      \n

    1. Make a new branch from the recently released stable branch:

      \n
      Shell
      git checkout stable/A.B.x\ngit checkout -b update-translations-catalog-A.B.x\n
      \n
      2. \n

    2. Ensure that the release’s dedicated virtual environment is enabled and\nrun the following:

      \n
      Shell
      $ cd django\n$ django-admin makemessages -l en --domain=djangojs --domain=django\nprocessing locale en\n
      \n
      3. \n

    3. Review the diff before pushing and avoid committing changes to the\n.po files without any new translations (example commit).

      4. \n

    4. Make a pull request against the corresponding stable branch and merge\nonce approved.

      5. \n

    5. Forward port the updated source translations to the main branch\n(example commit).

      6. \n
    \n
    6. \n

  6. If this was an rc pre-release, call for translations for the upcoming\nrelease in the Django Forum - Internationalization category.

    7. \n
\n
\n
\n

Notes on setting the VERSION tupleLink to this heading#

\n

Django’s version reporting is controlled by the VERSION tuple in\ndjango/__init__.py. This is a five-element tuple, whose elements\nare:

\n
    \n

  1. Major version.

    2. \n

  2. Minor version.

    3. \n

  3. Micro version.

    4. \n

  4. Status – can be one of “alpha”, “beta”, “rc” or “final”.

    5. \n

  5. Series number, for alpha/beta/RC packages which run in sequence\n(allowing, for example, “beta 1”, “beta 2”, etc.).

    6. \n
\n

For a final release, the status is always “final” and the series\nnumber is always 0. A series number of 0 with an “alpha” status will\nbe reported as “pre-alpha”.

\n

Some examples:

\n\n
","rootId":"how-to-release-django","toc":[{"title":"Overview","anchor":"overview","children":[]},{"title":"Prerequisites","anchor":"prerequisites","children":[]},{"title":"Pre-release tasks","anchor":"pre-release-tasks","children":[{"title":"10 (or more) days before a security release","anchor":"or-more-days-before-a-security-release","children":[]},{"title":"A week before a security release","anchor":"a-week-before-a-security-release","children":[]},{"title":"A few days before any release","anchor":"a-few-days-before-any-release","children":[{"title":"A few days before a feature freeze","anchor":"a-few-days-before-a-feature-freeze","children":[]}]}]},{"title":"Feature freeze tasks","anchor":"feature-freeze-tasks","children":[]},{"title":"Actually rolling the release","anchor":"actually-rolling-the-release","children":[{"title":"Building the artifacts","anchor":"building-the-artifacts","children":[]}]},{"title":"Making the release(s) available to the public","anchor":"making-the-release-s-available-to-the-public","children":[]},{"title":"Post-release","anchor":"post-release","children":[]},{"title":"Notes on setting the VERSION tuple","anchor":"notes-on-setting-the-version-tuple","children":[]}],"breadcrumbs":[{"docname":"internals/index","title":"Django internals","url":"/en/5.2/internals/"}],"prev":{"docname":"internals/git","title":"The Django source code repository","url":"/en/5.2/internals/git/"},"next":null,"formats":{"html":"/en/5.2/internals/howto-release-django/","markdown":"/en/5.2/internals/howto-release-django.md","json":"/en/5.2/internals/howto-release-django.json"},"source":"https://github.com/django/django/blob/stable/5.2.x/docs/internals/howto-release-django.txt","official":"https://docs.djangoproject.com/en/5.2/internals/howto-release-django/","inVersions":["dev","6.1","6.0","5.2","5.1","5.0","4.2","4.1","4.0","3.2","3.1","3.0","2.2","2.1","2.0","1.11","1.10","1.9","1.8"],"inLocales":["en","sv","zh-hans","ga","fr","ja","id","it","pt-br","ko","es","el","pl"]}