Django 是如何形成的？

这份文档解释了如何发布 Django。

请在进行更改时保持这些说明的最新状态！ 这里的重点是描述性的，而不是规范性的，所以请随意简化或进行其他更改，但 相应地更新这份文档！

概况

有三种类型的发布可能需要进行：

  • 安全性发布：揭示和修复漏洞。这通常涉及到两个或三个同时发布的版本，例如 3.2.x、4.0.x，根据时间的安排，可能还包括 4.1.x。
  • 常规版本发布：可以是最终发布（例如 4.1）或错误修复更新（例如 4.1.1）。
  • 预发布版本：例如 4.2 alpha、beta 或 rc。

涉及的步骤的简短版本是：

  1. 如果这是一个安全性发布，请在实际发布前一周预先通知安全性发布列表。
  2. 校对发布说明，查找组织和写作错误。起草一篇博客文章和电子邮件公告。
  3. 更新版本号并创建发布包。
  4. 将包上传到 djangoproject.com 服务器。
  5. 验证包的签名，检查它们是否可以安装，并确保最小功能可用。
  6. 将新版本上传到 PyPI。
  7. 在 djangoproject.com 的管理员界面中声明新版本。
  8. 发布博客文章并发送电子邮件公告。
  9. 发布后更新版本号。

有很多细节，请继续阅读。

先决条件

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

  • A Unix environment with these tools installed (in alphabetical order):

    • bash
    • git
    • GPG
    • make
    • man
    • 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 Jenkins server running the “confirm release” job.

    More than one GPG key

    If the key you want to use is not your default signing key, you’ll need to add -u you@example.com to every GPG signing command shown below, where you@example.com is the email address associated with the key you want to use.

  • A clean Python virtual environment per Django version being released, with these required Python packages installed:

    1. $ python -m pip install build twine

  • Access to Django’s project on PyPI to upload binaries, ideally with extra permissions to yank a release if necessary. Create a project-scoped token following the official documentation and set up your $HOME/.pypirc file like this:

    ~/.pypirc

    1. [distutils]
    2.   index-servers =
    3.     pypi
    4.     django
    6. [pypi]
    7.   username = __token__
    8.   password = # User-scoped or project-scoped token, to set as the default.
    10. [django]
    11.   repository = https://upload.pypi.org/legacy/
    12.   username = __token__
    13.   password = # A project token.

  • Access to Django’s project on Transifex, with a Manager role. Generate an API Token in the user setting section and set up your $HOME/.transifexrc file like this:

    ~/.transifexrc

    1. [https://www.transifex.com]
    2.   rest_hostname = https://rest.api.transifex.com
    3.   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:

  • Access to the django-security repo in GitHub. Among other things, this provides access to the pre-notification distribution list (needed for security release preparation tasks).

发布前的任务

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

10 (or more) days before a security release

  1. Request the CVE IDs for the security issue(s) being released. One CVE ID per issue, requested with Vendor: djangoproject and Product: django.
  2. Generate the relevant (private) patch(es) using git format-patch, one for the main branch and one for each stable branch being patched.

A week before a security release

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

    1. $ gpg --clearsign --digest-algo SHA256 prenotification-email.txt

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

    1. Notice of upcoming Django security releases (3.2.24, 4.2.10 and 5.0.2)
    3. Django versions 5.0.2, 4.2.10, and 3.2.24 will be released on Tuesday,
    4. February 6th, 2024 around 1500 UTC. They will fix one security defect
    5. with severity "moderate".
    7. For details of severity levels, see:
    8. https://docs.djangoproject.com/en/dev/internals/security/#how-django-discloses-security-issues

A few days before any release

  1. 随着发布日期的临近，监视 Trac，确保即将发布的版本中没有任何阻碍发布的问题。

  2. 与其他合并人员核对，确保他们没有为发布而提交的未提交更改。

  3. 校对发布说明，包括查看在线版本以 捕捉任何损坏的链接 或 reST 错误，并确保发布说明包含正确的日期。

  4. 再次确认发布说明中提到了任何已经标记为弃用的 API 的弃用时间表，并且提到了对 Python 版本支持的任何更改。

  5. 再次检查发布说明索引中是否有指向新发布版本说明的链接；这将在 docs/releases/index.txt 中。

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

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

    1. $ python scripts/manage_translations.py fetch

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

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

    1. $ 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"

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

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

  7. 更新 django-admin 手册页面：

    1. $ cd docs
    2. $ make man
    3. $ man _build/man/django-admin.1  # do a quick sanity check
    4. $ cp _build/man/django-admin.1 man/django-admin.1

    然后提交已更改的手册页面。

  8. 如果这是一个新系列的 alpha 版本，请从主分支创建一个新的稳定分支。例如，发布 Django 4.2 时：

    1. $ git checkout -b stable/4.2.x origin/main
    2. $ git push origin -u stable/4.2.x:stable/4.2.x

    同时，在稳定发布分支上的 docs/conf.py 中更新 django_next_version 变量，将其指向新的开发版本。例如，创建 stable/4.2.x 时，在新分支上将 django_next_version 设置为 '5.0'。

  9. 如果这是一个新系列的 “点零” 发布，请从当前稳定分支在 django-docs-translations 存储库中创建一个新分支。例如，发布 Django 4.2 时：

    1. $ git checkout -b stable/4.2.x origin/stable/4.1.x
    2. $ git push origin stable/4.2.x:stable/4.2.x

  10. 为发布撰写公告博客文章。你可以随时输入它到管理员界面并将其标记为非活动状态。以下是一些示例：示例安全发布公告、示例常规发布公告、示例预发布公告。

实际发布版本

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

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

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

    1. For a feature release, remove the UNDER DEVELOPMENT header at the top of the release notes, remove the Expected prefix and update the release date, if necessary (example commit).
    2. For a patch release, remove the Expected prefix and update the release date for all releases, if necessary (example commit).

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

    1. $ git checkout stable/4.1.x
    2. $ git pull

  4. 如果这是一个安全发布，请从 django-security 合并适当的补丁。根据需要重新基于这些补丁，使每个补丁都成为发布分支上的普通提交，而不是合并提交。为了确保这一点，使用 --ff-only 标志合并它们，例如：

    1. $ git checkout stable/4.1.x
    2. $ git merge --ff-only security/4.1.x

    （这假设 security/4.1.x 是 django-security 存储库中包含下一个 4.1 系列发布所需的安全补丁的分支。）

    如果 git 拒绝使用 --ff-only 合并，请切换到 security-patch 分支，并在你将要合并的分支上重新基于它（git checkout security/4.1.x; git rebase stable/4.1.x），然后切换回来并执行合并操作。确保每个安全修复的提交消息解释了这个提交是一个安全修复，并且会有一个公告随后发布（示例安全提交）。

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

    1. If this is a pre-release package also update the “Development Status” trove classifier in pyproject.toml to reflect this. An rc pre-release should not change the trove classifier (example commit for alpha release, example commit for beta release).
    2. Otherwise, make sure the classifier is set to Development Status :: 5 - Production/Stable.

  6. 使用 git tag 标记发布。例如：

    1. $ git tag --sign --message="Tag 4.1.1" 4.1.1

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

  7. Push your work and the new tag:

    1. $ git push
    2. $ git push --tags

  8. 确保你的代码库是绝对干净的，通过运行 git clean -dfx。

  9. Run python -m build to generate the release packages. This will create the release packages in a dist/ directory.

  10. 生成发布包的哈希值：

    1. $ cd dist
    2. $ md5sum *
    3. $ sha1sum *
    4. $ sha256sum *

  11. 创建一个名为 Django-<<VERSION>>.checksum.txt 的 “checksums” 文件，其中包含哈希值和发布信息。使用以下模板，并插入正确的版本、日期、GPG 密钥 ID（从 gpg --list-keys --keyid-format LONG 获取）、发布管理器的 GitHub 用户名、发布 URL 和哈希值：

    1. This file contains MD5, SHA1, and SHA256 checksums for the source-code
    2. tarball and wheel files of Django <<VERSION>>, released <<DATE>>.
    4. To use this file, you will need a working install of PGP or other
    5. compatible public-key encryption software. You will also need to have
    6. the Django release manager's public key in your keyring. This key has
    7. the ID ``XXXXXXXXXXXXXXXX`` and can be imported from the MIT
    8. keyserver, for example, if using the open-source GNU Privacy Guard
    9. implementation of PGP:
    11.    gpg --keyserver pgp.mit.edu --recv-key XXXXXXXXXXXXXXXX
    13. or via the GitHub API:
    15.    curl https://github.com/<<RELEASE MANAGER GITHUB USERNAME>>.gpg | gpg --import -
    17. Once the key is imported, verify this file:
    19.    gpg --verify <<THIS FILENAME>>
    21. Once you have verified this file, you can use normal MD5, SHA1, or SHA256
    22. checksumming applications to generate the checksums of the Django
    23. package and compare them to the checksums listed below.
    25. Release packages
    26. ================
    28. https://www.djangoproject.com/m/releases/<<MAJOR VERSION>>/<<RELEASE TAR.GZ FILENAME>>
    29. https://www.djangoproject.com/m/releases/<<MAJOR VERSION>>/<<RELEASE WHL FILENAME>>
    31. MD5 checksums
    32. =============
    34. <<MD5SUM>>  <<RELEASE TAR.GZ FILENAME>>
    35. <<MD5SUM>>  <<RELEASE WHL FILENAME>>
    37. SHA1 checksums
    38. ==============
    40. <<SHA1SUM>>  <<RELEASE TAR.GZ FILENAME>>
    41. <<SHA1SUM>>  <<RELEASE WHL FILENAME>>
    43. SHA256 checksums
    44. ================
    46. <<SHA256SUM>>  <<RELEASE TAR.GZ FILENAME>>
    47. <<SHA256SUM>>  <<RELEASE WHL FILENAME>>

  12. 签名 “checksum” 文件（gpg --clearsign --digest-algo SHA256 Django-<version>.checksum.txt）。这将生成一个已签名的文档，Django-<version>.checksum.txt.asc，你可以使用 gpg --verify Django-<version>.checksum.txt.asc 来验证它。

将发布版本提供给公众

现在，你准备好将发布版本发布出去了。为了做到这一点：

  1. 上传 checksum 文件：

    1. $ scp Django-A.B.C.checksum.txt.asc djangoproject.com:/home/www/www/media/pgp/Django-A.B.C.checksum.txt

    (If this is a security release, what follows should be done 15 minutes before the announced release time, no sooner.)

  2. 将发布包上传到 djangoproject 服务器，将 A.B. 替换为相应的版本号，例如，对于 4.1.x 发布，请将其替换为 4.1：

    1. $ scp Django-* djangoproject.com:/home/www/www/media/releases/A.B

    If this is the alpha release of a new series, you will need to create first the directory A.B.

  3. 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):

    1. $ RELEASE_VERSION='4.1.1'
    2. $ MAJOR_VERSION=`echo $RELEASE_VERSION| cut -c 1-3`
    4. $ python -m venv django-pip-tarball
    5. $ . django-pip-tarball/bin/activate
    6. $ python -m pip install https://www.djangoproject.com/m/releases/$MAJOR_VERSION/Django-$RELEASE_VERSION.tar.gz
    7. $ django-admin startproject test_tarball
    8. $ cd test_tarball
    9. $ ./manage.py --help  # Ensure executable bits
    10. $ python manage.py migrate
    11. $ python manage.py runserver
    12. <CTRL+C>
    13. $ deactivate
    14. $ cd .. && rm -rf test_tarball && rm -rf django-pip-tarball
    16. $ python -m venv django-pip-wheel
    17. $ . django-pip-wheel/bin/activate
    18. $ python -m pip install https://www.djangoproject.com/m/releases/$MAJOR_VERSION/Django-$RELEASE_VERSION-py3-none-any.whl
    19. $ django-admin startproject test_wheel
    20. $ cd test_wheel
    21. $ ./manage.py --help  # Ensure executable bits
    22. $ python manage.py migrate
    23. $ python manage.py runserver
    24. <CTRL+C>
    25. $ deactivate
    26. $ cd .. && rm -rf test_wheel && rm -rf django-pip-wheel

  4. 在 Jenkins 上运行 confirm-release 构建，以验证 checksum 文件（例如，对于 https://media.djangoproject.com/pgp/Django-4.2rc1.checksum.txt，使用 4.2rc1）。

  5. 将发布包上传到 PyPI（对于预发布版本，只上传 wheel 文件）：

    1. $ twine upload dist/*

  6. 前往管理员界面的 Add release page，输入新的版本号，确保与 tarball 名称中的版本号完全一致（Django-<version>.tar.gz）。例如，输入 “4.1.1” 或 “4.2rc1” 等。如果发布属于 LTS 分支，请标记为 LTS。

    如果这是新系列的 alpha 发布，还要为 最终 发布创建一个 Release 对象，确保 Release date 字段为空，从而标记为 未发布。例如，创建 4.2a1 的 Release 对象时，也创建一个 4.2，其中 Release date 字段为空。

  7. 发布公告发布的博客文章。

  8. 对于新版本发布（例如 4.1、4.2），通过将 docs.djangoproject.com 数据库中适当的 DocumentRelease 对象上的 is_default 标志设置为 True 来更新文档的默认稳定版本（这将自动将其设置为 False，对于所有其他版本）；你可以使用站点的管理员界面来完成这个操作。

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

    1. $ git checkout stable/4.2.x
    2. $ git pull
    3. $ python manage_translations.py robots_txt

  9. 将发布公告发布到 django-announce、django-developers、django-users 邮件列表以及 Django 论坛。这应包括一个指向公告博客文章的链接。

  10. 如果这是一个安全发布，请发送单独的电子邮件到 oss-security@lists.openwall.com。提供一个描述性的主题，例如，”Django” 加上发布说明中的问题标题（包括 CVE ID）。消息正文应包括漏洞详细信息，例如，公告博客文章的内容。包括一个指向公告博客文章的链接。

  11. 在 #django IRC 频道的主题中添加一个指向博客文章的链接：/msg chanserv TOPIC #django new topic goes here。

发布后

你差不多完成了！现在剩下要做的只有：

  1. 再次更新 django/__init__.py 中的 VERSION 元组，增加到下一个预期的发布版本。例如，在发布 4.1.1 后，将 VERSION 更新为 VERSION = (4, 1, 2, 'alpha', 0)。
  2. 如果需要的话，在 Trac 的版本列表 中添加发布（如果是最终发布，请通过修改 code.djangoproject.com 的 trac.ini 中的 default_version 设置将其设置为默认版本）。新的 X.Y 版本应该在 alpha 发布之后添加，并且在 “点零” 发布之后更新默认版本。
  3. If this was a final release:
    1. Update the current stable branch and remove the pre-release branch in the Django release process on Trac.
    2. Update djangoproject.com’s download page (example PR).
  4. 如果这是一个安全发布，请更新 安全问题档案，提供解决问题的详细信息。

新稳定分支任务

在创建新的稳定分支（通常在 alpha 版本发布后）后，有几项任务需要在接下来的时间内完成。其中一些任务不需要由发布者完成。

  1. Create a new DocumentRelease object in the docs.djangoproject.com database for the new version’s docs, and update the docs/fixtures/doc_releases.json JSON fixture, so people without access to the production DB can still run an up-to-date copy of the docs site (example PR).
  2. 为新的功能版本创建一个简化版的发布说明。可以使用上一个功能版本的简化版或者复制上一个功能版本的内容，然后删除大部分内容，只保留标题。
  3. 将 django.contrib.auth.hashers.PBKDF2PasswordHasher 中的默认 PBKDF2 迭代次数增加约 20%（选择一个整数）。运行测试，并使用新值更新 3 个失败的哈希器测试。确保在发布说明中有记录（查看 4.1 版本说明以获取示例）。
  4. 移除已经达到弃用周期末的功能。每个移除操作应该在单独的提交中完成，以确保清晰可见。在提交消息中，如果可能的话，添加一个 “refs #XXXX” 到最初的弃用开始的问题。
  5. 从两个版本前的文档中删除 .. versionadded::、.. versionadded:: 和 .. deprecated:: 注释。例如，在 Django 4.2 中，将删除 4.0 版本的注释。
  6. 将新分支添加到 Read the Docs。由于自动生成的版本名称（”stable-A.B.x”）与 Read the Docs 中使用的版本名称（”A.B.x”）不同，因此请创建一个 票务请求 请求新版本。
  7. 在 PyPI 上请求新的分类器。例如 Framework :: Django :: 3.1。
  8. 更新当前处于活跃开发中的分支，并在 Trac 上的 Django 发布流程 中添加预发布分支。

关于设置 VERSION 元组的注意事项

Django 的版本报告受控于 django/__init__.py 中的 VERSION 元组。这是一个包含五个元素的元组，其元素分别是：

  1. 主要版本。
  2. 次要版本。
  3. 微版本。
  4. 状态 — 可以是 “alpha”、”beta”、”rc” 或 “final” 中的一个。
  5. 系列号，用于按顺序运行的 alpha/beta/RC 包（例如，”beta 1”、”beta 2” 等）。

对于最终发布，状态始终为 “final”，系列号始终为 0。状态为 “alpha” 的系列号为 0 将被报告为 “pre-alpha”。

一些示例：

  • (4, 1, 1, "final", 0) → “4.1.1”
  • (4, 2, 0, "alpha", 0) → “4.2 pre-alpha”
  • (4, 2, 0, "beta", 1) → “4.2 beta 1”