Django 是如何形成的？¶

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

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

概况¶

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

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

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

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

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

先决条件¶

在开始之前，你需要准备一些东西。如果这是你第一次发布，你需要与另一位发布者协调，确保所有事项都准备妥当，并写信给 Ops 邮件列表，请求所需的访问权限和许可。

一个安装了以下工具的 Unix 环境（按字母顺序排列）：
- bash
- git
- GPG
- make
- man
- 哈希工具（通常在 Linux 上是 md5sum、sha1sum 和 sha256sum，在 macOS 上是 md5 和 shasum）
- python
- ssh
一个 GPG 密钥对。确保此密钥的私钥部分安全存储。公钥部分需要上传到你的 GitHub 账户，以及运行“确认发布”作业的 Jenkins 服务器。

多个 GPG 密钥

如果你想使用的密钥不是你的默认签名密钥，你需要在下面显示的每个 GPG 签名命令中添加 -u you@example.com，其中 you@example.com 是与你想要使用的密钥关联的电子邮件地址。
每个要发布的 Django 版本都需要一个干净的 Python 虚拟环境，并安装以下必需的 Python 包：
```
$ python -m pip install build twine
```

访问 Django 在 PyPI 上的项目以上传二进制文件，最好具有在必要时撤回发布的额外权限。按照官方文档创建一个项目范围的令牌，并按如下方式设置你的 $HOME/.pypirc 文件：

~/.pypirc¶

[distutils]
  index-servers =
    pypi
    django

[pypi]
  username = __token__
  password = # User-scoped or project-scoped token, to set as the default.

[django]
  repository = https://upload.pypi.org/legacy/
  username = __token__
  password = # A project token.

访问 Django 在 Transifex 上的项目，并具有管理员角色。在用户设置部分生成一个 API 令牌，并按如下方式设置你的 $HOME/.transifexrc 文件：
~/.transifexrc¶
```
[https://www.transifex.com]
  rest_hostname = https://rest.api.transifex.com
  token = # API token
```
访问 djangoproject.com 服务器以上传文件（使用 scp）。
作为“站点维护者”访问 djangoproject.com 上的 Django 管理界面。
访问 Django 论坛 - 公告类别以创建帖子，并发送电子邮件到以下邮件列表：
- django-announce
访问 GitHub 中的 django-security 仓库。除其他事项外，这提供了对预通知分发列表的访问权限（安全发布准备任务所需）。

发布前的任务¶

在开始发布过程之前，需要处理一些事项。这些工作大约在发布前一周开始；大部分工作可以在实际发布前的任何时间完成。

安全发布前 10 天（或更早）¶

为即将发布的安全问题请求 CVE ID。每个问题一个 CVE ID，请求时使用 Vendor: djangoproject 和 Product: django。
使用 git format-patch 生成相关的（私有）补丁，一个用于 main 分支，一个用于每个正在修补的稳定分支。

安全发布前一周¶

在安全发布前一周发送预通知。该电子邮件的模板和收件人列表在私有的 django-security GitHub wiki 中。将预通知收件人放在密件抄送中，并确保包含相关的 CVE ID。附上所有相关的补丁（针对 main 和稳定分支），并使用你将用于发布的密钥对电子邮件文本进行签名，命令如下：
```
$ gpg --clearsign --digest-algo SHA256 prenotification-email.txt
```

通知 django-announce 即将发布的安全版本，使用如下一般消息：

Notice of upcoming Django security releases (3.2.24, 4.2.10 and 5.0.2)

Django versions 5.0.2, 4.2.10, and 3.2.24 will be released on Tuesday,
February 6th, 2024 around 1500 UTC. They will fix one security defect
with severity "moderate".

For details of severity levels, see:
https://docs.djangoproject.com/en/dev/internals/security/#how-django-discloses-security-issues

任何发布前几天¶

As the release approaches, watch Trac to make sure no release blockers are left for the upcoming release. Under exceptional circumstances, such as to meet a pre-determined security release date, a release could still go ahead with an open release blocker. The releaser is trusted with the decision to release with an open release blocker or to postpone the release date of a non-security release if required.
与其他合并人员核对，确保他们没有为发布而提交的未提交更改。
校对发布说明，包括查看在线版本以捕捉任何损坏的链接或 reST 错误，并确保发布说明包含正确的日期。
再次确认发布说明中提到了任何已经标记为弃用的 API 的弃用时间表，并且提到了对 Python 版本支持的任何更改。
再次检查发布说明索引中是否有指向新发布版本说明的链接；这将在 docs/releases/index.txt 中。
如果这是一个功能发布，确保已集成来自 Transifex 的翻译。这通常由单独的翻译管理者而不是发布者完成，但以下是步骤。这个过程有点长，所以一定要预留 4-10 小时来完成，最好在发布日前一两天安排此任务。

除了配置好的 Transifex 账户外，tx CLI 应该在 PATH 中可用。然后，你可以通过运行以下命令获取所有翻译：
```
$ python scripts/manage_translations.py fetch
```
此命令需要一些时间运行。完成后，仔细检查输出以查找潜在的错误和/或警告。如果有，你需要逐个调试并解决它们。

最近获取的翻译需要一些手动调整。首先，PO-Revision-Date 值必须手动更新为晚于 POT-Creation-Date。你可以使用类似于以下的命令批量更新所有 .po 文件（与相关稳定分支进行比较）：
```
$ 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"
```
所有新的 .po 文件都应手动仔细检查，以避免提交没有任何新翻译的文件的更改。此外，“复数形式”不应有任何更改：如果有（通常是西班牙语和法语报告此更改），则需要还原。

最后，提交更改/添加的文件（.po 和 .mo），并创建一个针对相应发布稳定分支的新 PR（例如更新 4.2 翻译的 PR）。

更新 django-admin 手册页面：

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

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

如果这是一个新系列的 alpha 版本，请从主分支创建一个新的稳定分支。例如，发布 Django 4.2 时：
```
$ git checkout -b stable/4.2.x origin/main
$ 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'。
如果这是一个新系列的 "点零" 发布，请从当前稳定分支在 django-docs-translations 存储库中创建一个新分支。例如，发布 Django 4.2 时：
```
$ git checkout -b stable/4.2.x origin/stable/4.1.x
$ git push origin stable/4.2.x:stable/4.2.x
```
为发布撰写公告博客文章。你可以随时输入它到管理员界面并将其标记为非活动状态。以下是一些示例：示例安全发布公告、示例常规发布公告、示例预发布公告。

实际发布版本¶

好的，这是有趣的部分，我们实际上要发布一个版本！如果你要发布 多个版本，请为每个版本重复这些步骤。

检查 Jenkins 是否为你要发布的版本显示绿色。在它变绿之前，你可能不应该发布版本，并且你应该确保最新的绿色运行包括你要发布的更改。
清理此版本的发布说明。在 main 中进行这些更改，并向后移植到特定版本发布说明所在的所有分支。
1. 对于功能发布，删除发布说明顶部的 UNDER DEVELOPMENT 标题，删除 Expected 前缀，并在必要时更新发布日期（示例提交）。
2. 对于补丁发布，删除所有版本的 Expected 前缀，并在必要时更新发布日期（示例提交）。
发布总是从发布分支开始，因此你应该确保你在最新的稳定分支上。此外，你应该为每个发布的版本准备一个干净且专用的虚拟环境。例如：
```
$ git checkout stable/4.1.x
$ git pull
```
如果这是一个安全发布，请从 django-security 合并适当的补丁。根据需要重新基于这些补丁，使每个补丁都成为发布分支上的普通提交，而不是合并提交。为了确保这一点，使用 --ff-only 标志合并它们，例如：
```
$ git checkout stable/4.1.x
$ 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），然后切换回来并执行合并操作。确保每个安全修复的提交消息解释了这个提交是一个安全修复，并且会有一个公告随后发布（示例安全提交）。
在 django/__init__.py 中更新发布版本的版本号。有关 VERSION 的详细信息，请参阅下面的设置 VERSION 元组的注意事项`_（:commit:`示例提交 <2719a7f8c161233f45d34b624a9df9392c86cc1b>）。
1. 如果这是一个预发布包，还要更新 pyproject.toml 中的“开发状态”分类器以反映这一点。rc 预发布不应更改分类器（alpha 发布的示例提交，beta 发布的示例提交）。
2. 否则，确保分类器设置为 Development Status :: 5 - Production/Stable。
使用 git tag 标记发布。例如：
```
$ git tag --sign --message="Tag 4.1.1" 4.1.1
```
你可以通过运行 git tag --verify <tag> 来检查你的工作。
推送你的工作和新标签：
```
$ git push
$ git push --tags
```
确保你的代码库是绝对干净的，通过运行 git clean -dfx。
运行 python -m build 生成发布包。这将在 dist/ 目录中创建发布包。

生成发布包的哈希值：

$ cd dist
$ md5sum *
$ sha1sum *
$ sha256sum *

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

This file contains MD5, SHA1, and SHA256 checksums for the source-code
tarball and wheel files of Django <<VERSION>>, released <<DATE>>.

To use this file, you will need a working install of PGP or other
compatible public-key encryption software. You will also need to have
the Django release manager's public key in your keyring. This key has
the ID ``XXXXXXXXXXXXXXXX`` and can be imported from the MIT
keyserver, for example, if using the open-source GNU Privacy Guard
implementation of PGP:

    gpg --keyserver pgp.mit.edu --recv-key XXXXXXXXXXXXXXXX

or via the GitHub API:

    curl https://github.com/<<RELEASE MANAGER GITHUB USERNAME>>.gpg | gpg --import -

Once the key is imported, verify this file:

    gpg --verify <<THIS FILENAME>>

Once you have verified this file, you can use normal MD5, SHA1, or SHA256
checksumming applications to generate the checksums of the Django
package and compare them to the checksums listed below.

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>>

MD5 checksums
=============

<<MD5SUM>>  <<RELEASE TAR.GZ FILENAME>>
<<MD5SUM>>  <<RELEASE WHL FILENAME>>

SHA1 checksums
==============

<<SHA1SUM>>  <<RELEASE TAR.GZ FILENAME>>
<<SHA1SUM>>  <<RELEASE WHL FILENAME>>

SHA256 checksums
================

<<SHA256SUM>>  <<RELEASE TAR.GZ FILENAME>>
<<SHA256SUM>>  <<RELEASE WHL FILENAME>>

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

将发布版本提供给公众¶

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

上传 checksum 文件：
```
$ scp Django-A.B.C.checksum.txt.asc djangoproject.com:/home/www/www/media/pgp/Django-A.B.C.checksum.txt
```
（如果这是一个安全发布，接下来的步骤应在宣布的发布时间前 15 分钟完成，不要提前。）
将发布包上传到 djangoproject 服务器，将 A.B. 替换为相应的版本号，例如，对于 4.1.x 发布，请将其替换为 4.1：
```
$ scp Django-* djangoproject.com:/home/www/www/media/releases/A.B
```
如果这是一个新系列的 alpha 发布，你需要首先创建 A.B 目录。

使用 pip 测试发布包是否正确安装。这里有一个简单的方法（这仅测试二进制文件是否可用，是否正确安装，以及迁移和开发服务器是否启动，但它会捕捉愚蠢的错误）：

$ 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

在 Jenkins 上运行 confirm-release 构建，以验证 checksum 文件（例如，对于 https://media.djangoproject.com/pgp/Django-4.2rc1.checksum.txt，使用 4.2rc1）。
将发布包上传到 PyPI（对于预发布版本，只上传 wheel 文件）：
```
$ twine upload --repository django dist/*
```
前往管理员界面的 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 字段为空。
发布公告发布的博客文章。
对于新版本发布（例如 4.1、4.2），通过将 docs.djangoproject.com 数据库中适当的 DocumentRelease 对象上的 is_default 标志设置为 True 来更新文档的默认稳定版本（这将自动将其设置为 False，对于所有其他版本）；你可以使用站点的管理员界面来完成这个操作。

为每种语言创建新的 DocumentRelease 对象，这些语言在之前的发布中有条目。通过从 django-docs-translations 仓库的当前稳定分支运行命令 manage_translations.py robots_txt 生成的结果，更新 djangoproject.com 的 robots.docs.txt 文件。例如，当发布 Django 4.2 时：
```
$ git checkout stable/4.2.x
$ git pull
$ python manage_translations.py robots_txt
```
Post the release announcement to the django-announce mailing list and the Django Forum. This should include a link to the announcement blog post.
如果这是一个安全发布，请发送单独的电子邮件到 oss-security@lists.openwall.com。提供一个描述性的主题，例如，"Django" 加上发布说明中的问题标题（包括 CVE ID）。消息正文应包括漏洞详细信息，例如，公告博客文章的内容。包括一个指向公告博客文章的链接。

发布后¶

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

再次更新 django/__init__.py 中的 VERSION 元组，增加到下一个预期的发布版本。例如，在发布 4.1.1 后，将 VERSION 更新为 VERSION = (4, 1, 2, 'alpha', 0)。
如果需要的话，在 Trac 的版本列表中添加发布（如果是最终发布，请通过修改 code.djangoproject.com 的 trac.ini 中的 default_version 设置将其设置为默认版本）。新的 X.Y 版本应该在 alpha 发布之后添加，并且在 "点零" 发布之后更新默认版本。
如果这是一个最终发布：
1. 更新当前稳定分支并删除 Trac 上 Django 发布过程中的预发布分支。
2. 更新 djangoproject.com 的下载页面（示例 PR）。
如果这是一个安全发布，请更新安全问题档案，提供解决问题的详细信息。
If this was a pre-release, the translation catalogs need to be updated:
1. Make a new branch from the recently released stable branch:
```
git checkout stable/A.B.x
git checkout -b update-translations-catalog-A.B.x
```
2. Ensure that the release's dedicated virtual environment is enabled and run the following:
```
$ cd django
$ django-admin makemessages -l en --domain=djangojs --domain=django
processing locale en
```
3. Review the diff before pushing and avoid committing changes to the .po files without any new translations (example commit).
4. Make a pull request against the corresponding stable branch and merge once approved.
5. Forward port the updated source translations to the main branch (example commit).
If this was an rc pre-release, call for translations for the upcoming release in the Django Forum - Internationalization category.

新稳定分支任务¶

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

在 docs.djangoproject.com 数据库中为新版本的文档创建一个新的 DocumentRelease 对象，并更新 docs/fixtures/doc_releases.json JSON 夹具，以便没有访问生产数据库权限的人仍然可以运行最新的文档站点副本（示例 PR）。
为新的功能版本创建一个简化版的发布说明。可以使用上一个功能版本的简化版或者复制上一个功能版本的内容，然后删除大部分内容，只保留标题。
将 django.contrib.auth.hashers.PBKDF2PasswordHasher 中的默认 PBKDF2 迭代次数增加约 20%（选择一个整数）。运行测试，并使用新值更新 3 个失败的哈希器测试。确保在发布说明中有记录（查看 4.1 版本说明以获取示例）。
移除已经达到弃用周期末的功能。每个移除操作应该在单独的提交中完成，以确保清晰可见。在提交消息中，如果可能的话，添加一个 "refs #XXXX" 到最初的弃用开始的问题。
删除文档中两个版本前的 .. versionadded::、.. versionchanged:: 和 .. deprecated:: 注释。例如，在 Django 4.2 中，将删除 4.0 的注释。
将新分支添加到 Read the Docs。由于自动生成的版本名称（"stable-A.B.x"）与 Read the Docs 中使用的版本名称（"A.B.x"）不同，因此请创建一个票务请求请求新版本。
在 PyPI 上请求新的分类器。例如 Framework :: Django :: 3.1。
更新当前处于活跃开发中的分支，并在 Trac 上的 Django 发布流程中添加预发布分支。

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

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

主要版本。
次要版本。
微版本。
状态 -- 可以是 "alpha"、"beta"、"rc" 或 "final" 中的一个。
系列号，用于按顺序运行的 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"

Django 是如何形成的？¶

概况¶

先决条件¶

发布前的任务¶

安全发布前 10 天（或更早）¶

安全发布前一周¶

任何发布前几天¶

实际发布版本¶

将发布版本提供给公众¶

发布后¶

新稳定分支任务¶

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

Additional Information

Support Django!

Contents

Getting help

Download: