How is Django Formed?

本文解释如何释放Django。

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

Overview

您可能需要执行以下三种类型的发布:

  • 安全版本:披露和修复漏洞。这通常涉及两个或三个同时发布 - 例如。1.5.x,1.6.x,并且根据时间,可能是1.7α/β/ rc。
  • 常规版本:最终版本(例如1.5)或bugfix更新(例如。1.5.1)。
  • 预发布:例如1.6α,β或rc。

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

  1. 如果这是安全版本,请在实际发布前一周预先通知安全通讯组列表。
  2. 校对发行说明,寻找组织和写错误。起草博客文章和电子邮件公告。
  3. 更新版本号并创建发行包。
  4. 将软件包上传到djangoproject.com服务器。
  5. 除非这是一个预发布,添加新版本到PyPI。
  6. djangoproject.com上的管理员中声明新版本。
  7. 发布博客条目并发送电子邮件公告。
  8. 更新版本号后发布。

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

Prerequisites

在开始之前你需要一些东西:

  • GPG密钥。如果您要使用的密钥不是您的默认签名密钥,则需要将-u [email protected]添加到每个GPG签名命令,其中[email protected]是与您要使用的密钥相关联的电子邮件地址。

  • 安装一些必需的Python包:

    $ pip install wheel twine
    
  • 在PyPI上访问Django的记录。使用您的凭据创建文件:

    〜/ .pypirc
    [pypi]
    username:YourUsername
    password:YourPassword
    
  • 访问djangoproject.com服务器以上传文件。

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

  • 可以发布到django-announce

  • 如果这是安全发布,请访问预通知通讯组列表。

如果这是你的第一个版本,你需要与James和/或Jacob协调,以得到所有这些事情排队。

Pre-release tasks

甚至在开始发布过程之前,需要关注几个项目。这个东西在发布前一周开始;大多数可以做任何时间导致实际版本:

  1. 如果这是安全版本,请在发布之前发出一周的预通知。我们维护了在私人django-core存储库中获取这些预通知电子邮件的人员的列表。将邮件发送到[email protected],并将预通知收件人BCC。此电子邮件应该使用您用于发布的密钥进行签名,并且应包括每个已修复问题的修补程序。
  2. 随着发布接近,请观察Trac以确保没有释放阻滞剂留给即将发布的版本。
  3. 请与其他提交者确认,以确保他们没有任何未提交的版本更改。
  4. 校对发行说明,包括查看在线版本以捕获任何断开的链接或reST错误,并确保发行说明包含正确的日期。
  5. 仔细检查发布说明中是否提到了已弃用的任何API的弃用时间表,并提及Python版本支持中的任何更改。
  6. 仔细检查发行说明索引是否有指向新版本说明的链接;这将在docs/releases/index.txt中。

Preparing for release

写发布的公告博客文章。您可以随时将其输入到管理员,并将其标记为非活动。以下是几个示例:示例安全公告示例常规发布公告示例预发布公告

Actually rolling the release

OK,这是有趣的部分,我们实际推出一个发布!

  1. 检查Jenkins是绿色的您正在推出的版本。你可能不应该发布一个版本,直到它是绿色。

  2. 发布始终从发布分支开始,因此您应该确保您处于稳定的分支并且是最新的。例如:

    git checkout stable/1.5.x
    git pull
    
  3. 如果这是安全版本,请从django-private合并相应的修补程序。根据需要重新编写这些补丁,使每个补丁都是发布分支上的简单提交,而不是合并提交。要确保这一点,请将它们与--ff-only标志合并;例如:

    git checkout stable/1.5.x
    git merge --ff-only security/1.5.x
    

    (这假设security/1.5.xdjango-private库中的一个分支,包含1.5系列中下一个版本的必要安全补丁)。

    If git refuses to merge with --ff-only, switch to the security-patch branch and rebase it on the branch you are about to merge it into (git checkout security/1.5.x; git rebase stable/1.5.x) and then switch back and do the merge. 确保每个安全修补程序的提交消息都说明该提交是一个安全修复程序,并且随后会有通告(示例安全提交)。

  4. 对于主要版本,请删除发行说明顶部的UNDER 开发标题,并将发行日期添加到下一行。对于次要版本,将发布日期替换为* 开发*在特定版本的发行说明所在的所有分支上进行此更改。

  5. 在版本的django/__init__.py中更新版本号。有关VERSION的详细信息,请参阅下面的有关设置VERSION元组的注释。

    在1.4中,还应更新docs/conf.pysetup.py中的版本号。这里是一个示例提交更新版本号

  6. 如果这是预发布包,请更新setup.py中的“开发状态”trove分类以反映这一点。否则,请确保分类器设置为开发 状态 :: 5 / t5> 生产/稳定

  7. 使用git 标记标记版本。例如:

    git tag --sign --message="Tag 1.5.1" 1.5.1
    

    您可以运行git 标签 - 验证 < tag> t0 >。

  8. 推送您的工作,包括标记:git push - 标签

  9. 请通过运行git 清洁 -dfx确保您的树是完全干净的。

  10. 运行make -f extras / Makefile生成发行包。这将在dist/目录中创建发布包。注意,我们不发布1.4的轮文件。

  11. 生成发行包的散列:

    $ cd dist
    $ md5sum *
    $ sha1sum *
    $ sha256sum *
    
  12. 创建包含散列和发布信息的“校验和”文件,Django-<<VERSION>>.checksum.txt从此模板开始,插入正确的版本,日期,GPG密钥ID(从gpg - list-keys - keyid-format LONG),发布网址和校验和:

    This file contains MD5, SHA1, and SHA256 checksums for the source-code
    tarball 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
    
    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:
    =================
    
    Django <<VERSION>> (tar.tgz): https://www.djangoproject.com/m/releases/<<RELEASE TAR.GZ FILENAME>>
    Django <<VERSION>> (.whl): 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>>
    
  13. 签署校验和文件(gpg - clearsign - digest-algo SHA256 Django - &lt; version&gt; .checksum.txt)。这会产生签名的文档Django-<version>.checksum.txt.asc,您可以使用gpg t4> Django-&lt; version&gt; .checksum.txt.asc

如果您要发布多个发布,请对每个发布重复这些步骤。

Making the release(s) available to the public

现在你准备好把发行版放在那里了。去做这个:

  1. 将发行包上传到djangoproject服务器,替换A.B.具有适当的版本号,例如1.5 for 1.5.x版本:

    $ scp Django-* djangoproject.com:/home/www/www/media/releases/A.B
    
  2. 上传校验和文件:

    $ scp Django-A.B.C.checksum.txt.asc djangoproject.com:/home/www/www/media/pgp/Django-A.B.C.checksum.txt
    
  3. 使用easy_installpip测试发行版包是否正确安装。这里有一个方法(需要virtualenvwrapper):

    $ RELEASE_VERSION='1.7.2'
    $ MAJOR_VERSION=`echo $RELEASE_VERSION| cut -c 1-3`
    
    $ mktmpenv
    $ easy_install https://www.djangoproject.com/m/releases/$MAJOR_VERSION/Django-$RELEASE_VERSION.tar.gz
    $ deactivate
    $ mktmpenv
    $ pip install https://www.djangoproject.com/m/releases/$MAJOR_VERSION/Django-$RELEASE_VERSION.tar.gz
    $ deactivate
    $ mktmpenv
    $ pip install https://www.djangoproject.com/m/releases/$MAJOR_VERSION/Django-$RELEASE_VERSION-py2.py3-none-any.whl
    $ deactivate
    

    这只是测试tarball是可用的(即。重定向是up),并且他们正确安装,但它会捕获愚蠢的错误。

  4. 要求IRC上的几个人通过访问校验和文件来验证校验和。https://www.djangoproject.com/m/pgp/Django-1.5b1.checksum.txt),然后按照其中的说明操作。对于奖励积分,他们还可以解压缩下载的发行版tarball,并验证其内容是否正确(正确的版本号,没有杂乱.pyc或其他不需要的文件)。

  5. 将发行包上传到PyPI:

    $ twine upload -s dist/*
    
  6. 转到管理员中的添加发布页面,输入完整地显示在tarball名称(Django- .tar.gz)中的新版本号。 例如输入“1.5.1”或“1.4-rc-2”等。如果发布是LTS分支的一部分,请将其标记为。

  7. 让博客帖子宣布发布实况。

  8. 对于新版本发布(例如1.5, 1.6), update the default stable version of the docs by flipping the is_default flag to True on the appropriate DocumentRelease object in the docs.djangoproject.com database (this will automatically flip it to False for all others); you can do this using the site’s admin.

  9. 将发布通知发布到django-announcedjango-developersdjango-users邮件列表。这应该包括到公告博客帖子的链接。

Post-release

你几乎完成!现在剩下要做的是:

  1. django/__init__.py中再次更新VERSION元组,增加到下一个预期版本的任何值。例如,在释放1.5.1后,将VERSION更新为VERSION = (1, 5, 2, 'alpha', 0)
  2. 如有必要,请将版本添加到Trac的版本列表(如果是最终版本,请将其设为默认值)。并非所有版本都已声明;采取以前版本的例子。
  3. 如果这是安全版本,请更新Archive of security issues,其中包含所解决问题的详细信息。

New stable branch tasks

在创建新的稳定分支(通常是在alpha版本之后)之后,有几个项目要做。这些任务中的一些不需要由释放者来完成。

  1. 在新版本文档的docs.djangoproject.com数据库中创建新的DocumentRelease对象,并更新docs/fixtures/doc_releases.json JSON夹具,所以人们无法访问生产数据库仍然可以运行docs网站的最新副本。
  2. 为新的主版本创建存根发行说明。使用上一主版本的存根,或使用以前的主版本,并删除大部分内容,只留下节标题。
  3. django.contrib.auth.hashers.PBKDF2PasswordHasher中的默认PBKDF2迭代次数增加约20%(选择一个轮数)。运行测试,并使用新值更新3个失败的哈希测试。确保这在发行说明中被记录(有关示例,请参阅1.8发行说明)。
  4. 删除已过期的功能。为了清楚起见,每个删除应在单独的提交中完成。在提交消息中,向原始票证添加“refs #XXXX”,如果可能的话,弃用开始。
  5. Remove .. versionadded::, .. versionadded::, and .. deprecated:: annotations in the documentation from two releases ago. 例如,在Django 1.9中,1.7的注释将被删除。

Notes on setting the VERSION tuple

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将被报告为“前-α”。

一些例子:

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