diff --git a/docs/internals/howto-release-django.txt b/docs/internals/howto-release-django.txt index 75e1f372d4..4c86265ab3 100644 --- a/docs/internals/howto-release-django.txt +++ b/docs/internals/howto-release-django.txt @@ -15,12 +15,12 @@ There are three types of releases that you might need to make: * Security releases: disclosing and fixing a vulnerability. This'll generally involve two or three simultaneous releases -- e.g. - 1.5.x, 1.6.x, and, depending on timing, perhaps a 1.7 alpha/beta/rc. + 3.2.x, 4.0.x, and, depending on timing, perhaps a 4.1.x. -* Regular version releases: either a final release (e.g. 1.5) or a - bugfix update (e.g. 1.5.1). +* Regular version releases: either a final release (e.g. 4.1) or a + bugfix update (e.g. 4.1.1). -* Pre-releases: e.g. 1.6 alpha, beta, or rc. +* Pre-releases: e.g. 4.2 alpha, beta, or rc. The short version of the steps involved is: @@ -139,12 +139,12 @@ any time leading up to the actual release: and then commit the changed man page. #. If this is the alpha release of a new series, create a new stable branch - from main. For example, when releasing Django 3.1: + from main. For example, when releasing Django 4.2: .. code-block:: shell - $ git checkout -b stable/3.1.x origin/main - $ git push origin -u stable/3.1.x:stable/3.1.x + $ git checkout -b stable/4.2.x origin/main + $ git push origin -u stable/4.2.x:stable/4.2.x At the same time, update the ``django_next_version`` variable in ``docs/conf.py`` on the stable release branch to point to the new @@ -154,12 +154,12 @@ any time leading up to the actual release: #. If this is the "dot zero" release of a new series, create a new branch from the current stable branch in the `django-docs-translations `_ repository. For - example, when releasing Django 2.2: + example, when releasing Django 4.2: .. code-block:: shell - $ git checkout -b stable/2.2.x origin/stable/2.1.x - $ git push origin stable/2.2.x:stable/2.2.x + $ git checkout -b stable/4.2.x origin/stable/4.1.x + $ git push origin stable/4.2.x:stable/4.2.x Preparing for release ===================== @@ -188,7 +188,7 @@ OK, this is the fun part, where we actually push out a release! .. code-block:: shell - $ git checkout stable/1.5.x + $ git checkout stable/4.1.x $ git pull #. If this is a security release, merge the appropriate patches from @@ -198,25 +198,25 @@ OK, this is the fun part, where we actually push out a release! .. code-block:: shell - $ git checkout stable/1.5.x - $ git merge --ff-only security/1.5.x + $ git checkout stable/4.1.x + $ git merge --ff-only security/4.1.x - (This assumes ``security/1.5.x`` is a branch in the ``django-security`` repo - containing the necessary security patches for the next release in the 1.5 + (This assumes ``security/4.1.x`` is a branch in the ``django-security`` repo + containing the necessary security patches for the next release in the 4.1 series.) If git refuses to merge with ``--ff-only``, switch to the security-patch branch and rebase it on the branch you are about to merge it into (``git - checkout security/1.5.x; git rebase stable/1.5.x``) and then switch back and + checkout security/4.1.x; git rebase stable/4.1.x``) and then switch back and do the merge. Make sure the commit message for each security fix explains that the commit is a security fix and that an announcement will follow (:commit:`example security commit `). #. For a feature release, remove the ``UNDER DEVELOPMENT`` header at the top of the release notes and add the release date on the next line. For a - patch release, replace ``*Under Development*`` with the release date. Make - this change on all branches where the release notes for a particular version - are located. + patch release, remove the ``Expected`` prefix and update the release date, + if necessary. Make this change on all branches where the release notes for a + particular version are located. #. Update the version number in ``django/__init__.py`` for the release. Please see `notes on setting the VERSION tuple`_ below for details @@ -230,7 +230,7 @@ OK, this is the fun part, where we actually push out a release! .. code-block:: shell - $ git tag --sign --message="Tag 1.5.1" 1.5.1 + $ git tag --sign --message="Tag 4.1.1" 4.1.1 You can check your work by running ``git tag --verify ``. @@ -282,26 +282,26 @@ OK, this is the fun part, where we actually push out a release! checksumming applications to generate the checksums of the Django package and compare them to the checksums listed below. - Release packages: - ================= + Release packages + ================ - https://www.djangoproject.com/m/releases/<> - https://www.djangoproject.com/m/releases/<> + https://www.djangoproject.com/m/releases/<>/<> + https://www.djangoproject.com/m/releases/<>/<> - MD5 checksums: - ============== + MD5 checksums + ============= <> <> <> <> - SHA1 checksums: - =============== + SHA1 checksums + ============== <> <> <> <> - SHA256 checksums: - ================= + SHA256 checksums + ================ <> <> <> <> @@ -319,7 +319,7 @@ Making the release(s) available to the public Now you're ready to actually put the release out there. To do this: #. Upload the release package(s) to the djangoproject server, replacing - A.B. with the appropriate version number, e.g. 1.5 for a 1.5.x release: + A.B. with the appropriate version number, e.g. 4.1 for a 4.1.x release: .. code-block:: shell @@ -339,7 +339,7 @@ Now you're ready to actually put the release out there. To do this: .. code-block:: shell - $ RELEASE_VERSION='1.7.2' + $ RELEASE_VERSION='4.1.1' $ MAJOR_VERSION=`echo $RELEASE_VERSION| cut -c 1-3` $ python -m venv django-pip @@ -354,12 +354,11 @@ Now you're ready to actually put the release out there. To do this: This just tests that the tarballs are available (i.e. redirects are up) and that they install correctly, but it'll catch silly mistakes. -#. Ask a few people on IRC to verify the checksums by visiting the checksums - file (e.g. https://media.djangoproject.com/pgp/Django-1.5b1.checksum.txt) - and following the instructions in it. For bonus points, they can also unpack - the downloaded release tarball and verify that its contents appear to be - correct (proper version numbers, no stray ``.pyc`` or other undesirable - files). +#. Run the `confirm-release`__ build on Jenkins to verify the checksum file(s) + (e.g. use ``4.2rc1`` for + https://media.djangoproject.com/pgp/Django-4.2rc1.checksum.txt). + + __ https://djangoci.com/job/confirm-release/ #. Upload the release packages to PyPI (for pre-releases, only upload the wheel file): @@ -370,19 +369,19 @@ Now you're ready to actually put the release out there. To do this: #. 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 "1.5.1" or "1.4c2", etc. - If the release is part of an LTS branch, mark it so. + (``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. __ https://www.djangoproject.com/admin/releases/release/add/ If this is the alpha release of a new series, also create a Release object for the *final* release, ensuring that the *Release date* field is blank, thus marking it as *unreleased*. For example, when creating the Release - object for ``3.1a1``, also create ``3.1`` with the Release date field blank. + object for ``4.2a1``, also create ``4.2`` with the Release date field blank. #. Make the blog post announcing the release live. -#. For a new version release (e.g. 1.5, 1.6), update the default stable version +#. For a new version release (e.g. 4.1, 4.2), update the default stable version of the docs by flipping the ``is_default`` flag to ``True`` on the appropriate ``DocumentRelease`` object in the ``docs.djangoproject.com`` database (this will automatically flip it to ``False`` for all @@ -392,11 +391,11 @@ Now you're ready to actually put the release out there. To do this: for the previous release. Update djangoproject.com's `robots.docs.txt`__ file by copying entries from ``manage_translations.py robots_txt`` from the current stable branch in the ``django-docs-translations`` repository. For - example, when releasing Django 2.2: + example, when releasing Django 4.2: .. code-block:: shell - $ git checkout stable/2.2.x + $ git checkout stable/4.2.x $ git pull $ python manage_translations.py robots_txt @@ -422,8 +421,8 @@ You're almost done! All that's left to do now is: #. Update the ``VERSION`` tuple in ``django/__init__.py`` again, incrementing to whatever the next expected release will be. For - example, after releasing 1.5.1, update ``VERSION`` to - ``VERSION = (1, 5, 2, 'alpha', 0)``. + example, after releasing 4.1.1, update ``VERSION`` to + ``VERSION = (4, 1, 2, 'alpha', 0)``. #. Add the release in `Trac's versions list`_ if necessary (and make it the default by changing the ``default_version`` setting in the @@ -458,7 +457,7 @@ need to be done by the releaser. ``django.contrib.auth.hashers.PBKDF2PasswordHasher`` by about 20% (pick a round number). Run the tests, and update the 3 failing hasher tests with the new values. Make sure this gets noted in the - release notes (see the 1.8 release notes for an example). + release notes (see the 4.1 release notes for an example). #. Remove features that have reached the end of their deprecation cycle. Each removal should be done in a separate commit for clarity. In the commit @@ -467,7 +466,7 @@ need to be done by the releaser. #. Remove ``.. versionadded::``, ``.. versionadded::``, and ``.. deprecated::`` annotations in the documentation from two releases ago. For example, in - Django 1.9, notes for 1.7 will be removed. + Django 4.2, notes for 4.0 will be removed. #. Add the new branch to `Read the Docs `_. Since the automatically @@ -500,8 +499,8 @@ be reported as "pre-alpha". Some examples: -* ``(1, 2, 1, 'final', 0)`` → "1.2.1" +* ``(4, 1, 1, "final", 0)`` → "4.1.1" -* ``(1, 3, 0, 'alpha', 0)`` → "1.3 pre-alpha" +* ``(4, 2, 0, "alpha", 0)`` → "4.2 pre-alpha" -* ``(1, 3, 0, 'beta', 2)`` → "1.3 beta 2" +* ``(4, 2, 0, "beta", 1)`` → "4.2 beta 1"