blurb

概述

blurb 是一个旨在消除 CPython 核心开发中 Misc/NEWS 冲突的噩梦的工具。

核心概念：将 Misc/NEWS 分割成多个单独的文件，在排序后重新连接，恢复原始的 Misc/NEWS 文件。之后，可以从 CPython 仓库中删除 Misc/NEWS，并在需要时（例如构建发布版本时）按需生成。在向 CPython 提交更改时，提交过程将生成一个新的文件，并将其按正确的顺序排序，使用一个不太可能发生合并冲突的文件名。

blurb 是一个带有多个子命令的单个命令。它旨在在有效的 CPython（Git）仓库中运行，并自动使用正确的文件路径。

您可以使用 pip 从 PyPI 安装 blurb。或者，只需将 blurb 添加到您的路径上的目录中。

blurb 的唯一依赖是 Python 3.8+。

blurb 使用的文件

blurb 使用一个名为 Misc/NEWS.d 的新目录树。它所做的一切都在这里，除非可能修改 Misc/NEWS。

在 Misc/NEWS.d 下，您将找到以下内容

• 每个之前版本的新闻条目都只有一个文件，文件名以确切版本号命名，扩展名为 .rst。例如：Misc/NEWS.d/3.6.0b2.rst。

• 包含代表各种 Misc/NEWS 类别的子目录的 next 目录。在这些子目录中，有更多具有长、无聊、计算机生成的名称的 .rst 文件。例如：Misc/NEWS.d/next/Library/2017-05-04-12-24-06.gh-issue-25458.Yl4gI2.rst

blurb 子命令

像许多现代工具一样，blurb 只有一个可执行文件（称为 blurb），但它通过子命令提供了一系列的功能。子命令是命令行上指定的第一个参数。

如果您是 CPython 贡献者，您可能不需要使用除 blurb add 之外的内容——甚至不需要指定 add 部分。（如果没有指定子命令，blurb 假设您意味着 blurb add。）其他命令仅预期对 CPython 发布经理有用。

blurb 帮助

blurb 通过 blurb help 子命令进行自我文档化。在没有其他参数的情况下运行，它将打印所有子命令的列表，并简要概述每个命令的功能。运行带有第三个参数时，它将打印该子命令的帮助信息（例如 blurb help release）。

blurb add

blurb add 为您添加新的 Misc/NEWS 条目。它会在模板上打开一个文本编辑器；您编辑文件，保存并退出。然后 blurb 将文件存储在正确的位置，并在 Git 中为您将其提交。

blurb add 消息的模板看起来像这样

#
# Please enter the relevant GitHub issue number here:
#
.. gh-issue:

#
# Uncomment one of these "section:" lines to specify which section
# this entry should go in in Misc/NEWS.
#
#.. section: Security
#.. section: Core and Builtins
#.. section: Library
#.. section: Documentation
#.. section: Tests
#.. section: Build
#.. section: Windows
#.. section: macOS
#.. section: IDLE
#.. section: Tools/Demos
#.. section: C API

# Write your Misc/NEWS entry below.  It should be a simple ReST paragraph.
# Don't start with "- Issue #<n>: " or "- gh-issue<n>: " or that sort of stuff.
###########################################################################

以下是您如何与文件交互

• 将此提交的 GitHub 问题编号添加到 .. gh-issue: 行的末尾。

• 取消注释与该条目相关的 Misc/NEWS 节的行。例如，如果此条目应放入 Library 节，取消注释读取为 #.. section: Library 的行。取消注释只需删除该行的前面的 #。

• 最后，转到文件末尾，并输入您的 NEWS 条目。这应是一个使用简单 reST 标记的英文文本的段落。

当 blurb add 获取有效的条目时，它会按照以下格式将其写入文件

Misc/NEWS.d/next/<section>/<datetime>.gh-issue-<issue_number>.<nonce>.rst

例如，blurb add 添加的文件可能看起来像这样：

Misc/NEWS.d/next/Library/2017-05-04-12-24-06.gh-issue-25458.Yl4gI2.rst

<section> 是提交消息中提供的部分。

<datetime> 是当前的 UTC 时间，格式为 YYYY-MM-DD-hh-mm-ss。

<nonce> 是一个字符字符串，旨在防止文件名冲突。 blurb 通过计算文本的 MD5 哈希、将其转换为 base64（使用“urlsafe”字母表）并取该字符串的前 6 个字符来创建它。

此文件名确保了以下几点

• Misc/NEWS 中的所有条目都将按时间排序。

• 两个开发者在同一秒提交时，为两个开发者提交生成的文件名之间发生冲突的可能性极低。

最后，blurb add 将文件在 git 中为您提交。

blurb merge

blurb merge 将 Misc/NEWS.d 树中的所有文件重新组合成一个单一的 NEWS 文件。

blurb merge 只接受一个命令行参数：要写入的文件。默认情况下，它写入到相对于您的 CPython 检出根目录的 Misc/NEWS。

拆分和重新组合现有的 Misc/NEWS 文件并不会精确地重建之前的 Misc/NEWS。这是因为 Misc/NEWS 从未在每次发布中为“章节”使用一致的排序，而 blurb merge 对章节有硬编码的首选排序。此外，blurb 会积极地重新格式化段落，使其宽度小于 78 列，而原始手动编辑的文件偶尔会有大于 80 列的行。最后，blurb 严格使用 gh-issue-<n>: 在条目开头指定问题编号，而 Misc/NEWS 的传统方法需要使用 Issue #<n>:。

blurb release

blurb release 被发布经理作为 CPython 发布过程的一部分使用。它恰好接受一个参数，即正在发布的版本名称。

以下是它在内部执行的操作

• 将 Misc/NEWS.d/next 目录中所有最近添加的 NEWS 条目合并到 Misc/NEWS.d/<version>.rst 中。
• 运行 blurb merge 以生成更新的 Misc/NEWS 文件。

一个隐藏功能：如果指定的版本是 .，blurb release 将使用 CPython 检出到的目录名称。 (当制作发布时，我通常会根据要发布的版本命名目录，使用此快捷方式可以节省我一些输入。)

“next” 目录

您可能已经注意到，blurb add 将新闻条目添加到名为 next 的目录中，而 blurb release 将这些新闻条目合并到以版本命名的单个文件中。为什么这样做呢？

首先，它使得命名下一个版本成为一个后期绑定决策。如果我们目前正在开发 3.6.5rc1，但有零日漏洞需要发布紧急的 3.6.5 最终版，我们不需要修复大量元数据。

其次，这意味着如果您向前或向后选择 cherry-pick 提交，您将自动获取 NEWS 条目。您不需要做任何修改——系统已经会做正确的事。如果 NEWS 条目已经写入最终版本目录，您在 cherry-picking 过程中需要移动这些条目。

版权

blurb 由 Larry Hastings 版权所有 2015-2018。根据贡献协议许可给 PSF。

变更日志

请参阅 CHANGELOG.md。