开发流程¶
此页面描述了为贡献 Twisted 而应遵循的流程。
如果您要进行 Twisted 本身的开发，或者您想利用尚未在编号版本中提供的最新功能（或错误修复），您可能需要从 Twisted Git 存储库中签出树。
“trunk”是主分支，所有当前开发都在这里进行。
签出和初始开发虚拟环境¶
Twisted 使用 Git 来跟踪代码更改。Git 教程可以在其他地方找到，特别是请参阅 Git 和 GitHub 学习资源
$ git clone https://github.com/twisted/twisted twisted
$ python3 -m venv ./venv
$ . venv/bin/activate
$ pip install -e .[dev]
$ pip install pre-commit
请注意，本文档中所有后续命令都假设您的 Twisted 虚拟环境处于活动状态。（但是，我们不会假设您已将其放入“./venv”中；您可以随意使用您熟悉的任何 Python 环境管理器。）
如果您配置它使用我们的忽略文件，git blame 的输出 将更好
$ cd twisted
$ git config blame.ignoreRevsFile .git-blame-ignore-revs
运行测试¶
测试由“trial”测试框架处理。它了解延迟和 Twisted 提供的任何其他好东西。要运行完整的单元测试套件，请执行以下操作
trial twisted
要运行单个测试文件（如 twisted/test/test_defer.py），请执行以下操作之一
trial twisted.test.test_defer
# or
trial twisted/test/test_defer.py
要运行与代码文件相关的任何测试，例如 twisted/protocols/imap4.py，请执行以下操作
trial --testmodule twisted/mail/imap4.py
这取决于 .py 文件是否具有适当的“test-case-name”标签，该标签指示哪些测试用例提供覆盖范围。有关使用“test-case-name”的详细信息，请参阅 测试标准 文档。在本例中，将运行 twisted.mail.test.test_imap 测试。
某些测试在“./_trial_temp”中创建临时文件，您可以检查这些文件以进行调试，但该目录将在每次后续测试运行时被删除，因此如果您正在调试某些文件系统代码，您可能需要先将其移开。
构建文档¶
Twisted 的叙述性文档——即来自“./docs/”中“.rst”文件的文档——由 Sphinx 生成。它的 API 参考文档——即来自“.py”文件中的文档字符串的文档——由 pydoctor 生成。
要将文档的 HTML 形式构建到“doc/”目录中，请执行以下操作。这将触发完整的构建，包括 API 文档
tox -e narrativedocs
firefox docs/_build/index.html
提交和预提交钩子¶
提交 PR 时，请先创建一个 GitHub 问题，并将 PR 分支的名称以关联的 GitHub 问题编号为前缀，以便我们可以轻松地交叉引用它们。例如，使用“1234-some-brach-name”作为修复问题“1234”的分支的名称。
为了加快您的 PR 的接受速度，您可能希望确保它在本地通过我们的预提交代码样式检查。如果您跳过此步骤，您可能会发现我们使用的服务（pre-commit）生成了一些重新格式化提交。我们不介意，所以您可以随意让计算机来做这项工作，但这可能会延长您等待自动测试运行的时间。
要设置“git”以在您每次提交代码时自动运行这些检查，请运行以下命令
pre-commit install
或者，要在每次提交之前手动触发检查，请运行以下命令
pre-commit
发行说明管理¶
由各个更改的作者负责为其更改编写高级描述。它们不是提交或合并消息。这些描述将被汇总到与 Twisted 版本一起分发的发行说明中。它们应该以一种帮助其他用户决定是否需要升级，或者某个缺陷是否在某个版本中修复的方式编写。
在开发过程中，为了避免生成提交冲突，我们使用 towncrier 工具来管理每个更改的单独新闻片段。在发布时，所有这些“发布片段”都会被汇总到我们唯一的 NEWS 发布文件中。
更改必须附带一个文件，其内容描述了该更改，至少在一个“newsfragments”目录中。每个子项目都有一个“newsfragments”目录，核心 Twisted 更改有一个根目录。如果更改影响 Twisted 的多个区域，则每个受影响的区域都可以有一个 newsfragments 条目来详细说明相关更改。条目必须是一个名为“<issue number>.<change type>”的文件（例如“1234.bugfix”）。您应该将“<issue number>”替换为更改正在解决的问题编号（如果解决多个问题，则应添加具有相同内容的多个文件）。“<change type>”扩展名将被以下文字字符串之一替换
feature - 添加新功能的问题
bugfix - 修复错误的问题
doc - 主要关于修复或改进文档（任何种类）的问题
removal - 弃用某些内容或删除已弃用内容的问题
misc - 非常小且不值得在 git 变更日志之外进行总结的问题。这些应该为空（它们的内容将被忽略）
要了解这些文件中的文本如何呈现给用户，请查看 NEWS.rst 真实的整体新闻文件]。编写这些文件之一的内容的目标是生成适合整体新闻文件的文本。
以下是一些可以帮助您编写良好新闻片段的建议
条目应包含适合最终用户的更改的高级描述。
当更改涉及 Python 代码时，句子的语法主语应是 Python 类/方法/函数/接口/变量/等，动词应是对象所做的事情。动词可以以“now”为前缀。
对于 bugfix，它可以包含对引入错误的版本的引用。
以下是一些示例。
功能
twisted.protocols.amp now raises InvalidSignature when bad arguments are passed to Command.makeArguments
The new module twisted.internet.endpoints provides an interface for specifying address families separately from socket types.
错误修复
twisted.internet.ssl.Certificate(...).getPublicKey().keyHash() now produces a stable value regardless of OpenSSL version. Unfortunately this means that it is different than the value produced by older Twisted versions.
twisted.names.secondary.SecondaryAuthority can now answer queries again (broken since 13.2.0).
The SSL server string endpoint parser (twisted.internet.endpoints.serverFromString) now constructs endpoints which, by default, disable the insecure SSLv3 protocol.
弃用
twisted.trial.util.findObject is now deprecated.
twisted.conch.insults.colors is now deprecated in favor of twisted.conch.insults.helper.
twisted.runner.procmon.ProcessMonitor's active, consistency, and consistencyDelay attributes are now deprecated.
删除
twisted.internet.interfaces.IReactorTime.cancelCallLater, deprecated since Twisted 2.5, has been removed.
Support for versions of pyOpenSSL older than 0.10 has been removed.
文档
The documentation for twisted.internet.defer.DeferredSemaphore now describes the actual usage for `limit` and `tokens` instance attributes.
The docstring for twisted.conch.ssh.userauth.SSHUserAuthClient is now clearer on how the preferredOrder instance variable is handled.
twisted.mail.alias now has full API documentation.
The howto document page of Deferred now has documentation about the cancellation.
您无需担心文件中的换行符；内容将在添加到 NEWS 文件时重新换行。
审查流程¶
要被接受到主分支中的任何更改都必须通过审查流程。
有关更多详细信息，请参阅 专门的审查流程页面。
回滚更改¶
如果一个变更集以某种方式引入了测试套件回归，或者被发现是不可取的，则需要回滚。
任何开发人员都可以回滚在支持的平台上引入测试套件回归的提交。回滚消息应尽可能明确。如果是失败，请将错误消息放在提交消息中，可能还会包含有关测试环境的更多详细信息。如果失败太多，可以将其放在问题跟踪器中，并在消息中添加引用。
在提交消息中使用“Reopens”标签来引用相关问题
Revert revision-sha: Brief description
A description of the problem, or a traceback if pertinent
Reopens: #issue-number
回滚的分支在合并之前需要再次审查。