diff --git a/docs/internals/howto-release-django.txt b/docs/internals/howto-release-django.txt index fe0b8368e2..5427ab31c0 100644 --- a/docs/internals/howto-release-django.txt +++ b/docs/internals/howto-release-django.txt @@ -1,5 +1,5 @@ ===================== -How is Django Formed? +How to release Django ===================== This document explains how to release Django. @@ -30,20 +30,26 @@ The short version of the steps involved is: #. Proofread the release notes, looking for organization and writing errors. Draft a blog post and email announcement. -#. Update version numbers and create the release package(s). +#. Update version numbers and create the release artifacts. -#. Upload the package(s) to the ``djangoproject.com`` server. +#. Create the new ``Release`` in the admin on ``djangoproject.com``. + + #. Set the proper date but ensure the flag ``is_active`` is disabled. + #. Upload the artifacts (tarball, wheel, and checksums). #. Verify package(s) signatures, check if they can be installed, and ensure minimal functionality. #. Upload the new version(s) to PyPI. -#. Declare the new version in the admin on ``djangoproject.com``. +#. Enable the ``is_active`` flag for each release in the admin on + ``djangoproject.com``. #. Post the blog entry and send out the email announcements. -#. Update version numbers post-release. +#. Update version numbers post-release in stable branch(es). + +#. Add stub release notes for the next patch release in ``main`` and backport. There are a lot of details, so please read on. @@ -65,7 +71,6 @@ permissions. * hashing tools (typically ``md5sum``, ``sha1sum``, and ``sha256sum`` on Linux, or ``md5`` and ``shasum`` on macOS) * python - * ssh * A GPG key pair. Ensure that the private part of this key is securely stored. The public part needs to be uploaded to your GitHub account, and also to the @@ -121,15 +126,12 @@ permissions. rest_hostname = https://rest.api.transifex.com token = # API token -* Access to the ``djangoproject.com`` server to upload files (using ``scp``). - * Access to the Django admin on ``djangoproject.com`` as a "Site maintainer". * Access to create a post in the `Django Forum - Announcements category - `_ and to send emails to - the following mailing lists: - - * `django-announce `_ + `_ and to send emails to + the `django-announce `_ + mailing list. * Access to the ``django-security`` repo in GitHub. Among other things, this provides access to the pre-notification distribution list (needed for @@ -457,6 +459,20 @@ issuing **multiple releases**, repeat these steps for each release. #. Otherwise, make sure the classifier is set to ``Development Status :: 5 - Production/Stable``. +Building the artifacts +---------------------- + +.. admonition:: Optionally use helper scripts + + You can streamline some of the steps below using helper scripts from the Wiki: + + * `Release script for versions 5.1 and newer + `_ + * `Release script for versions 5.0 and older + `_ + * `Test new version script + `_ + #. Tag the release using ``git tag``. For example: .. code-block:: shell @@ -465,17 +481,11 @@ issuing **multiple releases**, repeat these steps for each release. You can check your work running ``git tag --verify ``. -#. Push your work and the new tag: - - .. code-block:: shell - - $ git push - $ git push --tags - #. Make sure you have an absolutely clean tree by running ``git clean -dfx``. #. Run ``python -m build`` to generate the release packages. This will create - the release packages in a ``dist/`` directory. + the release artifacts (tarball and wheel) in a ``dist/`` directory. For + Django 5.0 or older, you need to run ``make -f extras/Makefile`` instead. #. Generate the hashes of the release packages: @@ -521,8 +531,8 @@ issuing **multiple releases**, repeat these steps for each release. Release packages ================ - https://www.djangoproject.com/m/releases/<>/<> - https://www.djangoproject.com/m/releases/<>/<> + https://www.djangoproject.com/download/<>/tarball/ + https://www.djangoproject.com/download/<>/wheel/ MD5 checksums ============= @@ -552,55 +562,36 @@ Making the release(s) available to the public Now you're ready to actually put the release out there. To do this: -#. Upload the checksum file(s): +#. Create a new ``Release`` entry in the `djangoproject.com's admin + `_. If this is a + security release, this should be done 15 minutes before the announced + release time, no sooner: - .. code-block:: shell + Version + Must match the version number as defined in the tarball + (``django-.tar.gz``). For example: "5.2", "4.1.1", or "4.2rc1". - $ scp Django-A.B.C.checksum.txt.asc djangoproject.com:/home/www/www/media/pgp/Django-A.B.C.checksum.txt + Is active + Set to False until the release is fully published (last step). - (If this is a security release, what follows should be done 15 minutes - before the announced release time, no sooner.) + LTS + Enable if the release is part of an :abbr:`LTS (Long Term Support)` + branch. -#. Upload the release package(s) to the djangoproject server, replacing - A.B. with the appropriate version number, e.g. 4.1 for a 4.1.x release: + Dates + Set the release date to today. This release will not be published until + ``is_active`` is enabled. - .. code-block:: shell - - $ scp Django-* djangoproject.com:/home/www/www/media/releases/A.B + Artifacts + Upload the tarball (``django-.tar.gz``), wheel + (``django--py3-none-any.whl``), and checksum + (``django-.checksum.txt.asc``) files created earlier. #. Test that the release packages install correctly using ``pip``. Here's one simple method (this just tests that the binaries are available, that they install correctly, and that migrations and the development server start, but it'll catch silly mistakes): - - .. code-block:: shell - - $ RELEASE_VERSION='4.1.1' - $ MAJOR_VERSION=`echo $RELEASE_VERSION| cut -c 1-3` - - $ python -m venv django-pip-tarball - $ . django-pip-tarball/bin/activate - $ python -m pip install https://www.djangoproject.com/m/releases/$MAJOR_VERSION/Django-$RELEASE_VERSION.tar.gz - $ django-admin startproject test_tarball - $ cd test_tarball - $ ./manage.py --help # Ensure executable bits - $ python manage.py migrate - $ python manage.py runserver - - $ deactivate - $ cd .. && rm -rf test_tarball && rm -rf django-pip-tarball - - $ python -m venv django-pip-wheel - $ . django-pip-wheel/bin/activate - $ python -m pip install https://www.djangoproject.com/m/releases/$MAJOR_VERSION/Django-$RELEASE_VERSION-py3-none-any.whl - $ django-admin startproject test_wheel - $ cd test_wheel - $ ./manage.py --help # Ensure executable bits - $ python manage.py migrate - $ python manage.py runserver - - $ deactivate - $ cd .. && rm -rf test_wheel && rm -rf django-pip-wheel + https://code.djangoproject.com/wiki/ReleaseTestNewVersion. #. Run the `confirm-release`__ build on Jenkins to verify the checksum file(s) (e.g. use ``4.2rc1`` for @@ -615,12 +606,15 @@ Now you're ready to actually put the release out there. To do this: $ twine upload --repository django dist/* -#. Go to the `Add release page in the admin`__, enter the new release number - exactly as it appears in the name of the tarball - (``Django-.tar.gz``). So for example enter "4.1.1" or "4.2rc1", - etc. If the release is part of an LTS branch, mark it so. +#. Update the newly created ``Release`` in the admin in ``djangoproject.com`` + and enable the ``is_active`` flag. - __ https://www.djangoproject.com/admin/releases/release/add/ +#. Push your work and the new tag: + + .. code-block:: shell + + $ git push + $ git push --tags #. Make the blog post announcing the release live.