[5.2.x] Refs #35980 -- Updated internal docs for artifact upload and release via admin site.

Recent updates to djangoproject.com extended the `Release` model to
support uploading and storing artifacts and checksum files. This branch
updates the "How to release Django" docs to match the new release flow.

Backport of 08dae5bd46a02a2e2798028c83d97b1894beffb8 from main.

1 files changed, 60 insertions, 66 deletions

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
-  <https://forum.djangoproject.com/c/announcements/7>`_ and to  send emails to
-  the following mailing lists:
-
-  * `django-announce <https://groups.google.com/g/django-announce/>`_
+  <https://forum.djangoproject.com/c/announcements/7>`_ and to send emails to
+  the `django-announce <https://groups.google.com/g/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,25 +459,33 @@ issuing **multiple releases**, repeat these steps for each release.
    #. Otherwise, make sure the classifier is set to
       ``Development Status :: 5 - Production/Stable``.
 
-#. Tag the release using ``git tag``. For example:
+Building the artifacts
+----------------------
 
-   .. code-block:: shell
+.. admonition:: Optionally use helper scripts
 
-        $ git tag --sign --message="Tag 4.1.1" 4.1.1
+    You can streamline some of the steps below using helper scripts from the Wiki:
 
-   You can check your work running ``git tag --verify <tag>``.
+    * `Release script for versions 5.1 and newer
+      <https://code.djangoproject.com/wiki/ReleaseScript>`_
+    * `Release script for versions 5.0 and older
+      <https://code.djangoproject.com/wiki/ReleaseScript5.0AndOlder>`_
+    * `Test new version script
+      <https://code.djangoproject.com/wiki/ReleaseTestNewVersion>`_
 
-#. Push your work and the new tag:
+#. Tag the release using ``git tag``. For example:
 
    .. code-block:: shell
 
-        $ git push
-        $ git push --tags
+        $ git tag --sign --message="Tag 4.1.1" 4.1.1
+
+   You can check your work running ``git tag --verify <tag>``.
 
 #. 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/<<MAJOR VERSION>>/<<RELEASE TAR.GZ FILENAME>>
-    https://www.djangoproject.com/m/releases/<<MAJOR VERSION>>/<<RELEASE WHL FILENAME>>
+    https://www.djangoproject.com/download/<<VERSION>>/tarball/
+    https://www.djangoproject.com/download/<<VERSION>>/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
+   <https://www.djangoproject.com/admin/releases/release/add/>`_. If this is a
+   security release, this should be done 15 minutes before the announced
+   release time, no sooner:
 
-   .. code-block:: shell
-
-        $ scp Django-A.B.C.checksum.txt.asc djangoproject.com:/home/www/www/media/pgp/Django-A.B.C.checksum.txt
+   Version
+     Must match the version number as defined in the tarball
+     (``django-<version>.tar.gz``). For example: "5.2", "4.1.1", or "4.2rc1".
 
-   (If this is a security release, what follows should be done 15 minutes
-   before the announced release time, no sooner.)
+   Is active
+     Set to False until the release is fully published (last step).
 
-#. 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:
+   LTS
+     Enable if the release is part of an :abbr:`LTS (Long Term Support)`
+     branch.
 
-   .. code-block:: shell
+   Dates
+     Set the release date to today. This release will not be published until
+     ``is_active`` is enabled.
 
-        $ scp Django-* djangoproject.com:/home/www/www/media/releases/A.B
+   Artifacts
+     Upload the tarball (``django-<version>.tar.gz``), wheel
+     (``django-<version>-py3-none-any.whl``), and checksum
+     (``django-<version>.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
-        <CTRL+C>
-        $ 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
-        <CTRL+C>
-        $ 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-<version>.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.