这份文档解释了如何发布 Django。
请在进行更改时保持这些说明的最新状态! 这里的重点是描述性的,而不是规范性的,所以请随意简化或进行其他更改,但 相应地更新这份文档!
有三种类型的发布可能需要进行:
涉及的步骤的简短版本是:
djangoproject.com
服务器。djangoproject.com
的管理员界面中声明新版本。有很多细节,请继续阅读。
在开始之前,你需要准备一些东西:
一个 GPG 密钥。如果你想要使用的密钥不是你的默认签名密钥,那么在下面的每个 GPG 签名命令中,你需要添加 -u you@example.com
,其中 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 IDs <https://cveform.mitre.org/>`_(使用 Vendor: djangoproject, Product: django 请求)和补丁。此外,:ref:`通知 django-announce <security-disclosure> 即将发布的安全版本。
随着发布日期的临近,监视 Trac,确保即将发布的版本中没有任何阻碍发布的问题。
与其他合并人员核对,确保他们没有为发布而提交的未提交更改。
校对发布说明,包括查看在线版本以 捕捉任何损坏的链接 或 reST 错误,并确保发布说明包含正确的日期。
再次确认发布说明中提到了任何已经标记为弃用的 API 的弃用时间表,并且提到了对 Python 版本支持的任何更改。
再次检查发布说明索引中是否有指向新发布版本说明的链接;这将在 docs/releases/index.txt
中。
如果这是一个功能发布,请确保来自 Transifex 的翻译已经被整合。通常,这是由独立的翻译管理员完成,而不是由发布者,但以下是步骤。假设你在 Transifex 上有帐户:
$ python scripts/manage_translations.py fetch
然后提交已更改/添加的文件(包括 .po
和 .mo
文件)。有时会出现需要调试的验证错误,因此避免在需要立即发布时立即执行此任务。
$ 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 是否对你要发布的版本(或版本)是正常的。在它变为正常之前,你可能不应该发布版本。
发布始终始于一个发布分支,所以你应该确保你在一个稳定的分支上,并且是最新的。例如:
$ 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
),然后切换回来并执行合并操作。确保每个安全修复的提交消息解释了这个提交是一个安全修复,并且会有一个公告随后发布(示例安全提交)。
对于功能发布,删除发布说明顶部的 UNDER DEVELOPMENT
标头,并在下一行添加发布日期。对于补丁发布,如果需要,删除 Expected
前缀并更新发布日期。在包含特定版本发布说明的所有分支上进行此更改。
在发布中更新 django/__init__.py
中的版本号。请参阅下面关于设置 VERSION
元组的注意事项以获取有关 VERSION
的详细信息。
如果这是一个预发布包,请在 setup.cfg
中更新 "Development Status" trove 分类以反映这一点。否则,请确保分类设置为 Development Status :: 5 - Production/Stable
。
使用 git tag
标记发布。例如:
$ git tag --sign --message="Tag 4.1.1" 4.1.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
的 "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
来验证它。
如果你要发布多个版本,为每个版本重复这些步骤。
现在,你准备好将发布版本发布出去了。为了做到这一点:
将发布包上传到 djangoproject 服务器,将 A.B. 替换为相应的版本号,例如,对于 4.1.x 发布,请将其替换为 4.1:
$ scp Django-* djangoproject.com:/home/www/www/media/releases/A.B
如果这是新系列的 alpha 发布,你需要创建目录 A.B。
上传 checksum 文件:
$ scp Django-A.B.C.checksum.txt.asc djangoproject.com:/home/www/www/media/pgp/Django-A.B.C.checksum.txt
使用 pip
测试发布包是否正确安装。以下是一种方法:
$ RELEASE_VERSION='4.1.1'
$ MAJOR_VERSION=`echo $RELEASE_VERSION| cut -c 1-3`
$ 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 是否可用(即重定向是否正常),以及它们是否正确安装,但它可以捕捉到愚蠢的错误。
在 Jenkins 上运行 confirm-release 构建,以验证 checksum 文件(例如,对于 https://media.djangoproject.com/pgp/Django-4.2rc1.checksum.txt,使用 4.2rc1
)。
将发布包上传到 PyPI(对于预发布版本,只上传 wheel 文件):
$ twine upload -s 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
将发布公告发布到 django-announce、django-developers、django-users 邮件列表以及 Django 论坛。这应包括一个指向公告博客文章的链接。
如果这是一个安全发布,请发送单独的电子邮件到 oss-security@lists.openwall.com。提供一个描述性的主题,例如,"Django" 加上发布说明中的问题标题(包括 CVE ID)。消息正文应包括漏洞详细信息,例如,公告博客文章的内容。包括一个指向公告博客文章的链接。
在 #django
IRC 频道的主题中添加一个指向博客文章的链接:/msg chanserv TOPIC #django new topic goes here
。
你差不多完成了!现在剩下要做的只有:
django/__init__.py
中的 VERSION
元组,增加到下一个预期的发布版本。例如,在发布 4.1.1 后,将 VERSION
更新为 VERSION = (4, 1, 2, 'alpha', 0)
。default_version
设置将其设置为默认版本)。新的 X.Y 版本应该在 alpha 发布之后添加,并且在 "点零" 发布之后更新默认版本。在创建新的稳定分支(通常在 alpha 版本发布后)后,有几项任务需要在接下来的时间内完成。其中一些任务不需要由发布者完成。
docs.djangoproject.com
数据库中为新版本的文档创建一个新的 DocumentRelease
对象,并更新 docs/fixtures/doc_releases.json
JSON fixture,以便没有访问生产数据库权限的人仍然可以运行一个最新的文档站点副本。django.contrib.auth.hashers.PBKDF2PasswordHasher
中的默认 PBKDF2 迭代次数增加约 20%(选择一个整数)。运行测试,并使用新值更新 3 个失败的哈希器测试。确保在发布说明中有记录(查看 4.1 版本说明以获取示例)。.. versionadded::
、.. versionadded::
和 .. deprecated::
注释。例如,在 Django 4.2 中,将删除 4.0 版本的注释。Framework :: Django :: 3.1
。Django 的版本报告受控于 django/__init__.py
中的 VERSION
元组。这是一个包含五个元素的元组,其元素分别是:
对于最终发布,状态始终为 "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"12月 04, 2023