Django 5.2.dev 文档

Home | Table of contents | Index | Modules

« previous | up

Django 是如何形成的？

本文档解释了如何释放Django。

Please, keep these instructions up-to-date if you make changes! 这里的重点是描述性的，而不是规定性的，所以请随意简化或以其他方式进行更改，但是 相应地更新此文档！

概述

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

• 安全发布：披露和修复漏洞。这通常包括两个或三个同时发布的版本--例如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. 验证包(S)签名，检查它们是否可以安装，并确保最低限度的功能。

6. 将新版本上载到pypi。

7. 在上的管理中声明新版本 djangoproject.com .

8. 发布日志并发送电子邮件通知。

9. 发布后更新版本号。

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

先决条件

在开始之前，您需要一些东西。如果这是您的第一个版本，您需要与另一个收件箱协调以安排所有这些事情，并写信到Ops邮件列表中请求所需的访问权限和权限。

• 安装了这些工具的Unix环境（按字母顺序）：

  • bash

  • git

  • GPG

  • 使

  • 人

  • 哈希工具（通常 md5sum ， sha1sum ，以及 sha256sum 在Linux上，或者 md5 和 shasum 在macOS上）

  • python

  • SSH

• GPG密钥对。确保此密钥的私有部分安全存储。公共部分需要上传到您的GitHub帐户，以及运行“确认发布”作业的Jenkins服务器。

  多个GPG密钥

  如果您要使用的密钥不是您的默认签名密钥，则需要添加 -u you@example.com 以下显示的每个GPG签名命令，其中 you@example.com 是与您要使用的密钥关联的电子邮件地址。

• 每个Django版本都会发布干净的Python虚拟环境，并安装了以下所需的Python包：

  $ python -m pip install build twine
  

• 获得 Django's project on PyPI 上传二进制文件，最好具有额外的权限 yank a release 必要时创建项目范围内的令牌 official documentation 并设置您的 $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's project on Transifex ，担任经理角色。在中生成API Token user setting section 并设置您的 $HOME/.transifexrc 文件如下所示：

  ~/.transifexrc

  [https://www.transifex.com]
    rest_hostname = https://rest.api.transifex.com
    token = # API token
  

• 访问 djangoproject.com 服务器上传文件（使用 scp )。

• 访问Django管理员 djangoproject.com 作为“网站维护者”。

• 访问在 Django Forum - Announcements category 并将电子邮件发送到以下邮寄列表：

  • django-users

  • django-developers

  • django-announce

• 访问 django-security GitHub中的回购。除其他外，这还提供了对预通知分发列表的访问权限（安全发布准备任务所需）。

发布前任务

甚至在开始发布过程之前都需要处理一些项目。这些内容大约在发布前一周开始;大部分内容可以在实际发布之前的任何时候完成。

安全发布前10（或更长）天

1. 请求 CVE IDs 针对正在发布的安全问题。每次问题一个UTE ID，要求与 Vendor: djangoproject 和 Product: django 。

2. 使用生成相关（私有）补丁 git format-patch ，一个为 main 分支，每个正在修补的稳定分支都有一个分支。

安全发布前一周

1. 准确发送预先通知 one week 在安全发布之前。该电子邮件的模板和收件人列表是私人的 django-security GitHub维基。抄送预通知收件人，并确保包含相关的UTE ID。附加所有相关补丁（目标 main 和稳定分支），并使用您将用于发布的密钥签署电子邮件文本，并使用以下命令：

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

2. Notify 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
   

发布前几天

1. 随着发布的临近，请观察trac以确保没有发布拦截器留给即将发布的版本。

2. 与其他合并者核对，以确保他们没有任何未提交的版本更改。

3. 校对发行说明，包括查看在线版本以 catch any broken links 或其他错误，并确保发行说明包含正确的日期。

4. 仔细检查发行说明中是否提到了被否决的任何API的否决时间线，以及是否提到了Python版本支持中的任何更改。

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

6. 如果这是一个 feature release ，确保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（示例 PR updating translations for 4.2 )。

7. Update the django-admin manual page ：

   $ 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
   

   然后提交更改的手册页。

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

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

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

9. 如果这是新系列的“点零”版本，请从 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
   

10. 撰写发布的公告日志。您可以随时将其输入管理员，并将其标记为不活动。以下是几个例子： `example security release announcement`_ _, `example regular release announcement`_ _, `example pre-release announcement`_ _.

实际滚动释放

好吧，这是有趣的部分，我们实际上推出了一个版本！如果您正在发行 multiple releases ，对每个版本重复这些步骤。

1. 检查 `Jenkins`__ 您要发布的版本为绿色。您可能不应该在绿色之前发布发布版本，并且您应该确保最新的绿色运行包含您正在发布的更改。

2. 卸载此版本的发行说明。做出这些改变 main 并回传到特定版本的发行说明所在的所有分支。

   1. 对于功能版本，请删除 UNDER DEVELOPMENT 发行说明顶部的标题，删除 Expected 如有必要，请加上发布日期并更新 (example commit )。

   2. 对于补丁发布，请删除 Expected 如有必要，请添加所有版本的发布日期并更新 (example commit )。

3. 发布总是从发布分支开始，因此您应该确保您处于最新的稳定分支。此外，您应该为每个发布的版本提供一个干净且专用的虚拟环境。例如：

   $ git checkout stable/4.1.x
   $ git pull
   

4. 如果这是安全版本，请合并来自 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系列下一版本所需的安全补丁的Repo。)

   如果Git拒绝与 --ff-only ，切换到安全补丁分支，并将其重新设置为您要将其合并到的分支 (git checkout security/4.1.x; git rebase stable/4.1.x )，然后切换回并执行合并。确保每个安全修补程序的提交消息说明该提交是一个安全修补程序，并且随后会发出通知 (example security commit )。

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. 如果这是预发布包，请更新中的“开发状态”宝藏分类器 pyproject.toml 以反映这一点。一个 rc 预发布不应改变宝藏分类器 (example commit for alpha release ， example commit for beta release )。

   2. 否则，确保分类器设置为 Development Status :: 5 - Production/Stable 。

6. 使用以下命令标记版本 git tag 。例如：

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

   您可以检查您的工作运行情况 git tag --verify <tag> 。

7. 推送您的作品和新标签：

   $ git push
   $ git push --tags
   

8. 确保你有一棵绝对干净的树 git clean -dfx .

9. 跑 python -m build 以生成发布包。这将在 dist/ 目录。

10. 生成版本包的哈希：

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

11. 创建“检查和”文件， 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/<<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>>
    

12. 签署校验和文件 (gpg --clearsign --digest-algo SHA256 Django-<version>.checksum.txt ）这将生成已签名的文档， Django-<version>.checksum.txt.asc 然后您可以使用 gpg --verify Django-<version>.checksum.txt.asc .

向公众发布

现在你已经准备好把释放装置放在那里了。这样做：

1. 上传校验和文件(S)：

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

   (If这是一个安全版本，以下内容应在宣布的发布时间前15分钟完成，不能更早。）

2. 将发布包(S)上传到djangoproject服务器，用适当的版本号替换A.B.，例如4.1x版本：

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

   如果这是新系列的Alpha版本，您将需要创建 first 目录AB

3. 使用以下命令测试发行包是否正确安装 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
   

4. 运行 `confirm-release`__ 以Jenkins为基础验证校验和文件(S)(例如，使用 4.2rc1 适用于https://media.djangoproject.com/pgp/Django-4.2rc1.checksum.txt).

5. 将发布包上传到PYPI(对于预发布，仅上传轮子文件)：

   $ twine upload dist/*
   

6. 转到 `Add release page in the admin`_ _，输入与tarball名称中显示的完全相同的新版本号 (Django-<version>.tar.gz )。例如，输入“4.1.1”或“4.2rc1”等。如果版本是LTS分支的一部分，则将其标记为“4.1.1”。

   如果这是新系列的Alpha版本，还要为 final 释放，确保 Release date 字段为空，因此将其标记为 unreleased 。例如，为创建Release对象时 4.2a1 ，还可以创建 4.2 释放日期字段为空。

7. 使发布的博客文章实时发布。

8. 对于新版本(例如4.1、4.2)，通过翻转 is_default 标志为 True 在适当的情况下 DocumentRelease 对象中的 docs.djangoproject.com 数据库(这会自动将其翻转到 False 对于所有其他用户)；您可以使用站点的管理员来完成此操作。

   创造新 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`__. 例如，当发布Django 4.2时：

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

9. 将发布公告发布到|Django-宣告|、django-developers、|Django-User|邮件列表和Django论坛。这应该包括一个到公告博客帖子的链接。

10. 如果这是安全版本，请发送单独的电子邮件至oss-security@lists.openwall.com。提供描述性主题，例如“Django”加上发行说明中的问题标题（包括UTE ID）。消息正文应包含漏洞详细信息，例如公告博客帖子文本。包括公告博客文章的链接。

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

释放后

你快完成了！现在只剩下：

1. 更新 VERSION 元组输入 django/__init__.py 再一次，递增到下一个预期的版本。例如，在发布4.1.1之后，更新 VERSION 至 VERSION = (4, 1, 2, 'alpha', 0) 。

2. 将发布添加 Trac's versions list 如有必要（并通过更改 default_version 设置在code.djangoproject.com的 `trac.ini`_ _，如果是最终版本）。新的X.Y版本应在Alpha发布后添加，默认版本应在“零点”发布后更新。

3. 如果这是最终版本：

   1. 更新当前稳定分支并删除中的预发布分支 Django release process 在Trac上。

   2. 更新djangoproject.com的下载页面 (example PR _)。

4. 如果这是一个安全版本，请更新 安全问题档案 解决问题的细节。

新的稳定分支任务

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

1. 创建新的 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. 增加中的默认PBKDF2迭代次数 django.contrib.auth.hashers.PBKDF2PasswordHasher 大约20%(挑一个整数)。运行测试，并使用新值更新3个失败的散列器测试。确保在发行说明中注明这一点(有关示例，请参阅4.1发行说明)。

4. 删除已达到其折旧周期结束的功能。为清晰起见，每次删除都应单独提交。在提交消息中，将“refs XXXX”添加到原始记录单中，如果可能，将在原始记录单中开始取消预测。

5. 移除 .. versionadded:: ， .. versionadded:: ，以及 .. deprecated:: 两个版本之前的文档中的注释。例如，在Django 4.2中，4.0的注释将被删除。

6. 将新分支添加到 Read the Docs 。由于自动生成的版本名称(“STRATE-A.B.x”)不同于在读取文档中使用的版本名称(“A.B.x”)， create a ticket 正在请求新版本。

7. Request the new classifier on PyPI <https://github.com/pypa/trove-classifiers/issues/29> _.例如 Framework :: Django :: 3.1 。

8. 更新Active Development下的当前分支，并在 Django release process 在Trac上。

关于设置版本元组的说明

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

1. 主要版本。

2. 次要版本。

3. 微版本。

4. 状态——可以是“alpha”、“beta”、“rc”或“final”之一。

5. 序列号，用于按顺序运行的alpha/beta/rc包（例如允许“beta 1”、“beta 2”等）。

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

一些例子：

• (4, 1, 1, "final", 0) →“4.1.1”

• (4, 2, 0, "alpha", 0) →“4.2Pre-Alpha”

• (4, 2, 0, "beta", 1) →“4.2测试版1”

Last update:

7月 22, 2024

« previous | up