姜戈是如何形成的？

本文档解释了如何发布 Django。

如果您进行更改，请保持这些说明是最新的！这里的重点是描述性的，而不是规定性的，所以请随意精简或以其他方式进行更改，但 相应地更新此文档!

概览

您可能需要发布三种类型的版本：

安全发布：披露和修复漏洞。这通常涉及两个或三个同时发布——例如 1.5.x、1.6.x，并且根据时间，可能是 1.7 alpha/beta/rc。
常规版本发布：要么是最终版本（例如 1.5）或错误修正更新（例如 1.5.1).
预发布：例如 1.6 alpha、beta 或 rc。

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

如果这是一次安全发布，请在实际发布前一周预先通知安全分发列表。
校对发行说明，寻找组织和写作错误。起草博客文章和电子邮件公告。
更新版本号并创建发布包。
将包上传到 djangoproject.com 服务器。
将新版本上传到 PyPI。
在 djangoproject.com 的管理员中声明新版本。
发布博客条目并发送电子邮件公告。
发布后更新版本号。

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

先决条件

在开始之前，您需要准备一些东西：

GPG 密钥。如果您要使用的密钥不是您的默认签名密钥，您需要将 -u you@example.com 添加到下面的每个 GPG 签名命令中，其中 you@example.com 是与您想要的密钥关联的电子邮件地址使用。
安装一些必需的 Python 包：
```
$ python -m pip install wheel twine
```
访问 Django 在 PyPI 上的记录。使用您的凭据创建一个文件：
~/.pypirc
```
[pypi]
username:YourUsername
password:YourPassword
```
访问djangoproject.com服务器上传文件。
以“站点维护者”的身份访问 djangoproject.com 上的管理员。
有权发布到 django-announce。
如果这是安全版本，请访问预通知分发列表。

如果这是您的第一个版本，您需要与另一个发布者协调以将所有这些内容都安排好。

预发布任务

在开始发布过程之前，需要注意一些事项。这些东西在发布前一周左右开始；大部分可以在实际发布之前的任何时间完成：

如果这是安全版本，请在发布前一周 发出预通知 。该电子邮件的模板和收件人列表位于私有 django-security GitHub wiki 中。密件抄送预通知收件人。使用您将用于发布的密钥对电子邮件进行签名，并包括 CVE ID（向供应商请求：djangoproject，产品：django）和每个正在修复的问题的补丁。此外，通知 django-announce 即将发布的安全版本。
随着发布的临近，请观看 Trac 以确保即将发布的版本没有发布阻止程序。
与其他提交者核对以确保他们没有任何未提交的版本更改。
校对发行说明，包括查看在线版本以发现任何断开的链接或 reST 错误，并确保发行说明包含正确的日期。
仔细检查发行说明是否提到了任何被标记为已弃用的 API 的弃用时间表，以及它们是否提及 Python 版本支持的任何更改。
仔细检查发行说明索引是否有指向新发行说明的链接；这将在 docs/releases/index.txt 中。
如果这是一个功能版本，请确保已集成来自 Transifex 的翻译。这通常由单独的翻译经理而不是发布者完成，但以下是步骤。如果您在 Transifex 上有一个帐户：
```
$ python scripts/manage_translations.py fetch
```
然后提交更改/添加的文件（.po 和 .mo）。有时需要调试验证错误，因此请避免在需要发布之前立即执行此任务。

更新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 版本，请从 main 创建一个新的稳定分支。例如，在发布 Django 3.1 时：
```
$ git checkout -b stable/3.1.x origin/main
$ git push origin -u stable/3.1.x:stable/3.1.x
```
同时更新稳定发布分支上docs/conf.py中的django_next_version变量指向新的开发版本。例如，创建stable/4.2.x时，在新分支上设置django_next_version为'5.0'。
如果这是新系列的“点零”版本，请从 django-docs-translations 存储库中的当前稳定分支创建一个新分支。例如，在发布 Django 2.2 时：
```
$ git checkout -b stable/2.2.x origin/stable/2.1.x
$ git push origin stable/2.2.x:stable/2.2.x
```

准备发布

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

实际滚动发布

好的，这是有趣的部分，我们实际上推出了一个版本！

检查 Jenkins 对于您要发布的版本是否为绿色。你可能不应该发布一个版本，直到它变成绿色。
一个发布总是从一个发布分支开始，所以你应该确保你在一个稳定的分支上并且是最新的。例如：
```
$ git checkout stable/1.5.x
$ git pull
```
如果这是一个安全版本，请从 django-security 合并相应的补丁。根据需要重新调整这些补丁，使每个补丁都成为发布分支上的普通提交，而不是合并提交。为确保这一点，请将它们与 --ff-only 标志合并；例如：
```
$ git checkout stable/1.5.x
$ git merge --ff-only security/1.5.x
```
（这假设 security/1.5.x 是 django-security 存储库中的一个分支，其中包含 1.5 系列下一个版本的必要安全补丁。）

如果 git 拒绝与 --ff-only 合并，请切换到 security-patch 分支并将其重新绑定到您将要合并到的分支 (git checkout security/1.5.x; git rebase stable/1.5.x) 上，然后切换回去进行合并。确保每个安全修复的提交消息都说明提交是一个安全修复并且随后会发布公告（ :commit:`示例安全提交 ` ）。
对于功能发布，删除发行说明顶部的 UNDER DEVELOPMENT 标题，并在下一行添加发布日期。对于补丁版本，将 *Under Development* 替换为发布日期。在特定版本的发行说明所在的所有分支上进行此更改。
更新 django/__init__.py 中的版本号。有关 VERSION 的详细信息，请参阅下面有关设置 VERSION 元组的注释。
如果这是预发布包，请更新 setup.cfg 中的“开发状态”宝库分类器以反映这一点。否则，请确保将分类器设置为 Development Status :: 5 - Production/Stable。
使用 git tag 标记版本。例如：
```
$ git tag --sign --message="Tag 1.5.1" 1.5.1
```
您可以通过运行 git tag --verify <tag> 来检查您的工作。
推送你的作品，包括标签：git push --tags。
通过运行 git clean -dfx 确保你有一个绝对干净的树。
运行 make -f extras/Makefile 生成发布包。这将在 dist/ 目录中创建发布包。

生成发布包的哈希值：

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

创建一个“校验和”文件，Django-<<VERSION>>.checksum.txt 包含哈希和发布信息。从这个模板开始，插入正确的版本、日期、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/<<RELEASE TAR.GZ FILENAME>>
https://www.djangoproject.com/m/releases/<<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>>

签署校验和文件 (gpg --clearsign --digest-algo SHA256 Django-<version>.checksum.txt)。这会生成一个签名文档 Django-<version>.checksum.txt.asc，然后您可以使用 gpg --verify Django-<version>.checksum.txt.asc 进行验证。

如果您要发布多个版本，请为每个版本重复这些步骤。

向公众提供版本

现在您已准备好实际发布该版本。去做这个：

将发布包上传到 djangoproject 服务器，替换 AB 使用适当的版本号，例如 1.5 版本的 1.5.x 版本：
```
$ scp Django-* djangoproject.com:/home/www/www/media/releases/A.B
```
如果这是新系列的 alpha 版本，则需要创建目录 AB

上传校验和文件：

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

使用 easy_install 和 pip 测试发布包是否正确安装。这是一种方法：

$ RELEASE_VERSION='1.7.2'
$ MAJOR_VERSION=`echo $RELEASE_VERSION| cut -c 1-3`

$ python -m venv django-easy-install
$ . django-easy-install/bin/activate
$ easy_install https://www.djangoproject.com/m/releases/$MAJOR_VERSION/Django-$RELEASE_VERSION.tar.gz
$ deactivate
$ python -m venv django-pip
$ . django-pip/bin/activate
$ python -m pip install https://www.djangoproject.com/m/releases/$MAJOR_VERSION/Django-$RELEASE_VERSION.tar.gz
$ deactivate
$ 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
$ deactivate

这只是测试 tarball 是否可用（即重定向已启动）并且它们安装正确，但它会捕获愚蠢的错误。

在 IRC 上请几个人通过访问校验和文件来验证校验和（例如 https://media.djangoproject.com/pgp/Django-1.5b1.checksum.txt) 并按照其中的说明进行操作。对于奖励积分，他们还可以解压缩下载的发行版 tarball 并验证其内容是否正确（正确的版本号，没有杂散的 .pyc 或其他不需要的文件）。
将发布包上传到 PyPI（对于预发布，只上传轮文件）：
```
$ twine upload -s dist/*
```
前往在管理中添加发布页面 , 输入与 tarball 名称中显示的完全相同的新版本号 (Django- .tar.gz）。因此，例如输入“1.5.1”或“1.4c2”等。如果发布是 LTS 分支的一部分，请标记它。

如果这是新系列的 alpha 版本，还要为 final 版本创建一个 Release 对象，确保 Release date 字段为空，从而将其标记为 unreleased 。例如，在为 3.1a1 创建发布对象时，还要创建 3.1，发布日期字段为空。
使宣布发布的博客文章实时发布。
对于新版本发布（例如 1.5、1.6），通过将 is_default 标志翻转到 True 来更新文档的默认稳定版本，在 docs.djangoproject.com 数据库中适当的 DocumentRelease 对象上（对于所有其他人，这将自动将其翻转为 False）；您可以使用该站点的管理员来执行此操作。

为具有上一版本条目的每种语言创建新的 DocumentRelease 对象。通过从 django-docs-translations 存储库中的当前稳定分支复制 manage_translations.py robots_txt 中的条目来更新 djangoproject.com 的 robots.docs.txt 文件。例如，在发布 Django 2.2 时：
```
$ git checkout stable/2.2.x
$ git pull
$ python manage_translations.py robots_txt
```
将发布公告发布到 django-announce、django-developers 和 django-users 邮件列表。这应该包括指向公告博客文章的链接。
如果这是安全版本，请发送单独的电子邮件至 oss-security@lists.openwall.com。提供描述性主题，例如“Django”加上发行说明中的问题标题（包括 CVE ID）。消息正文应包含漏洞详细信息，例如，公告博客文章文本。包括指向公告博客文章的链接。
在 #django IRC 频道的主题中添加博客文章链接：/msg chanserv TOPIC #django new topic goes here。

发布后

你几乎完成！现在剩下要做的就是：

再次更新 django/__init__.py 中的 VERSION 元组，递增到下一个预期版本。例如1.5.1发布后，将VERSION更新为VERSION = (1, 5, 2, 'alpha', 0)。
如有必要，在 Trac 的版本列表中添加版本（并通过更改 code.djangoproject.com 的 trac.ini 中的 default_version 设置使其成为默认值，如果它是最终版本）。新的 XY 版本应在 alpha 版本发布后添加，默认版本应在“点零”发布后更新。
如果这是一个安全版本，请更新安全问题存档并提供所解决问题的详细信息。

新的稳定分支任务

在创建新的稳定分支（通常在 alpha 版本之后）之后，有几件事要做。其中一些任务不需要由发布者完成。

在 docs.djangoproject.com 数据库中为新版本的文档创建一个新的 DocumentRelease 对象，并更新 docs/fixtures/doc_releases.json JSON 夹具，因此无法访问生产数据库的人仍然可以运行- 文档站点的最新副本。
为新功能版本创建存根发行说明。使用先前功能发布版本的存根或复制先前功能版本的内容并删除大部分内容，仅保留标题。
将 django.contrib.auth.hashers.PBKDF2PasswordHasher 中的默认 PBKDF2 迭代增加约 20%（选择一个整数）。运行测试，并使用新值更新 3 个失败的哈希器测试。确保在发行说明中对此进行了说明（有关示例，请参阅 1.8 发行说明）。
删除已达到弃用周期结束的功能。为清楚起见，每次删除都应在单独的提交中完成。在提交消息中，如果可能，将“refs #XXXX”添加到弃用开始的原始票证。
删除两个版本前文档中的 .. versionadded::、.. versionadded:: 和 .. deprecated:: 注释。例如，在 Django 1.9 中，将删除 1.7 的注释。
将新分支添加到阅读文档。由于自动生成的版本名称（“stable-ABx”）与阅读文档（“ABx”）中使用的版本名称不同，创建一个请求新版本的票证。
在 PyPI 上请求新的分类器。例如Framework :: Django :: 3.1。

设置 VERSION 元组的注意事项

Django 的版本报告由 django/__init__.py 中的 VERSION 元组控制。这是一个五元素元组，其元素是：

主要版本。
次要版本。
微版。
状态 - 可以是“alpha”、“beta”、“rc”或“final”之一。
系列号，用于按顺序运行的 alpha/beta/RC 包（例如，允许“beta 1”、“beta 2”等）。

对于最终版本，状态始终为“最终”且序列号始终为 0。具有“alpha”状态的序列号 0 将被报告为“pre-alpha”。

一些例子：

(1, 2, 1, 'final', 0) → “1.2.1”
(1, 3, 0, 'alpha', 0) → “1.3 pre-alpha”
(1, 3, 0, 'beta', 2) → “1.3 beta 2”

姜戈是如何形成的？ — Django 文档