为 Scrapy 贡献代码

重要

请确保您正在阅读此文档的最新版本：https://docs.scrapy.net.cn/en/master/contributing.html

有很多方法可以为 Scrapy 做贡献。以下是一些方法：

• 在 问题跟踪器 中报告错误并提出功能请求，请尽量遵循下面 报告错误 中详细说明的指南。

• 提交实现新功能和/或修复错误的补丁。请阅读下面的 编写补丁 和 提交补丁，了解如何编写和提交补丁。

• 撰写关于 Scrapy 的博文。告诉全世界你是如何使用 Scrapy 的。这将帮助新手获得更多示例，并有助于提高 Scrapy 项目的知名度。

• 加入 Scrapy subreddit 并分享你关于如何改进 Scrapy 的想法。我们始终欢迎建议。

• 在 Stack Overflow 上回答 Scrapy 相关问题。

报告错误

注意

请**仅**向 scrapy-security@googlegroups.com 报告安全问题。这是一个仅对可信的 Scrapy 开发人员开放的私有列表，其存档不公开。

编写良好的错误报告非常有帮助，因此在准备报告新错误时，请记住以下准则。

• 首先查看 常见问题解答，看看您的问题是否已在常见问题中得到解答。

• 如果您对 Scrapy 的使用有任何一般性问题，请在 Stack Overflow 上提问（使用“scrapy”标签）。

• 查看 已打开的问题，看看该问题是否已被报告。如果已被报告，请不要忽视该报告，而是检查票证历史记录和评论。如果您有其他有用的信息，请留下评论，或者考虑 发送包含修复的拉取请求。

• 搜索 scrapy-users 列表和 Scrapy subreddit，看看它是否已在那里讨论过，或者如果您不确定您看到的是否是错误。您也可以在 #scrapy IRC 频道中提问。

• 编写**完整、可复现、具体的错误报告**。测试用例越小越好。请记住，其他开发人员不会拥有您的项目来重现错误，因此请包含重现错误所需的所有相关文件。例如，请参阅 StackOverflow 关于创建展示问题的 最小、完整且可验证的示例 的指南。

• 提供完整可复现示例的最佳方式是发送一个拉取请求，该请求将失败的测试用例添加到 Scrapy 测试套件中（请参阅 提交补丁）。即使您没有打算自己修复此问题，这也很有帮助。

• 包含 scrapy version -v 的输出，以便处理您错误的开发人员确切地知道它在哪个版本和平台上发生，这通常对重现错误或了解它是否已被修复非常有帮助。

编写补丁

Scrapy 有一个 适合新手的问题 和 需要帮助的问题 列表，您可以参与其中。这些问题是开始为 Scrapy 做贡献的好方法。如果您不熟悉代码库，您可能需要专注于文档或与测试相关的问题，因为它们始终有用，并且可以帮助您更熟悉该项目。您还可以查看 Scrapy 的 测试覆盖率，以了解哪些区域可能需要更多测试。

补丁写得越好，被接受的可能性就越大，合并的速度就越快。

编写良好的补丁应：

• 包含特定更改所需的最小代码量。小的补丁更容易审查和合并。因此，如果您进行多个更改（或错误修复），请考虑每个更改提交一个补丁。不要将多个更改合并到一个补丁中。对于大的更改，请考虑使用补丁队列。

• 通过所有单元测试。请参阅下面 运行测试。

• 包含一个（或多个）测试用例，以检查修复的错误或添加的新功能。请参阅下面 编写测试。

• 如果您正在添加或更改公共（已记录）API，请在同一补丁中包含文档更改。请参阅下面 文档策略。

• 如果您正在添加私有 API，请在 docs/conf.py 的 coverage_ignore_pyobjects 变量中添加正则表达式，以从文档覆盖率检查中排除新的私有 API。

  要查看您的私有 API 是否已正确跳过，请按如下方式生成文档覆盖率报告：

  tox -e docs-coverage
  

• 如果您要删除已弃用的代码，请首先确保自引入弃用声明的版本发布以来至少已过 1 年（12 个月）。请参阅 弃用策略。

提交补丁

提交补丁的最佳方式是在 GitHub 上发出 拉取请求，可以选择先创建一个新问题。

请记住解释修复的内容或新功能（是什么，为什么需要，等等）。您提供的信息越多，核心开发人员就越容易理解和接受您的补丁。

您也可以在创建补丁之前讨论新功能（或错误修复），但始终最好准备一个补丁来阐述您的论点，并表明您已对主题进行了一些额外的思考。一个好的起点是在 GitHub 上发送一个拉取请求。它可以足够简单地说明您的想法，并在稍后验证和证明该想法有用后，再添加文档/测试。或者，您可以在 Scrapy subreddit 中开始对话，以首先讨论您的想法。

有时您要解决的问题已经有了一个现有的拉取请求，但由于某些原因而处于停滞状态。通常拉取请求的方向是正确的，但 Scrapy 维护人员请求更改，而原始拉取请求作者没有时间解决这些更改。在这种情况下，请考虑接手此拉取请求：使用原始拉取请求中的所有提交以及解决提出的问题的其他更改打开一个新的拉取请求。这样做非常有帮助；只要承认原始作者并保留其提交，就不会被认为是不礼貌的。

您可以通过运行 git fetch upstream pull/$PR_NUMBER/head:$BRANCH_NAME_TO_CREATE 将现有的拉取请求拉取到本地分支（将“upstream”替换为 scrapy 存储库的远程名称，$PR_NUMBER 替换为拉取请求的 ID，并将 $BRANCH_NAME_TO_CREATE 替换为您想要在本地创建的分支的名称）。另请参阅：https://githubdocs.cn/en/pull-requests/collaborating-with-pull-requests/reviewing-changes-in-pull-requests/checking-out-pull-requests-locally#modifying-an-inactive-pull-request-locally。

在编写 GitHub 拉取请求时，请尝试使标题简短但描述性。例如，对于错误 #411：“如果 start_requests 中引发异常，Scrapy 会挂起”，请使用“修复 start_requests 中发生异常时挂起的问题 (#411)”而不是“#411 的修复”。完整的标题使浏览问题跟踪器变得更容易。

最后，请尝试将美学更改（PEP 8 兼容性、删除未使用的导入等）与功能更改分开提交。这将使拉取请求更容易审查，更有可能被合并。

代码风格

在编写要包含在 Scrapy 中的代码时，请遵循以下代码约定：

• 我们使用 black 进行代码格式化。提交前检查配置中有一个钩子，会在每次提交前自动格式化您的代码。您也可以使用 tox -e pre-commit 手动运行 black。

• 不要在您贡献的代码中添加您的姓名；git 提供了足够的元数据来识别代码的作者。有关设置说明，请参阅 https://githubdocs.cn/en/get-started/getting-started-with-git/setting-your-username-in-git。

提交前检查

我们使用 pre-commit 在每次提交前自动解决简单的代码问题。

在您创建 Scrapy 存储库的分支的本地克隆后：

1. 安装 pre-commit：.

2. 在您本地克隆的 Scrapy 代码库的根目录下，运行以下命令

   pre-commit install
   

现在，每次您创建 Git 提交时，pre-commit 都会检查您的更改。如果发现问题，pre-commit 会中止您的提交，并自动修复这些问题，或者仅向您报告这些问题。如果它自动修复了这些问题，则再次创建提交应该会成功。否则，您可能需要先手动解决相应的问题。

文档策略

对于 API 成员（类、方法等）的参考文档，请使用文档字符串，并确保 Sphinx 文档使用 autodoc 扩展来提取文档字符串。API 参考文档应遵循文档字符串约定 (PEP 257) 并对 IDE 友好：简短、切中要害，并可以提供简短的示例。

其他类型的文档，例如教程或主题，应包含在 docs/ 目录中的文件中。这包括特定于 API 成员的文档，但超出了 API 参考文档的范围。

在任何情况下，如果某些内容包含在文档字符串中，请使用 autodoc 扩展将文档字符串提取到文档中，而不是在 docs/ 目录中的文件中复制文档字符串。

涵盖新功能或修改功能的文档更新必须使用 Sphinx 的 versionadded 和 versionchanged 指令。使用 VERSION 作为版本，我们将在对应版本发布之前将其替换为实际版本。当我们发布 Scrapy 的新主版本或次版本时，如果这些指令超过 3 年，我们将删除它们。

关于已弃用功能的文档必须在这些功能被弃用时删除，以便新读者不会遇到它。新的弃用和弃用移除在 发行说明 中有记录。

测试

测试是使用 Twisted 单元测试框架 实现的。运行测试需要 tox。

运行测试

要运行所有测试

tox

要运行特定的测试（例如 tests/test_loader.py），请使用

tox -- tests/test_loader.py

要在特定的 tox 环境中运行测试，请使用 -e <name> 并使用来自 tox.ini 的环境名称。例如，要使用 Python 3.10 运行测试，请使用

tox -e py310

您还可以指定一个用逗号分隔的环境列表，并使用 tox 的并行模式 在多个环境中并行运行测试

tox -e py39,py310 -p auto

要将命令行选项传递给 pytest，请在您对 tox 的调用中 -- 后添加它们。使用 -- 会覆盖 tox.ini 中定义的默认位置参数，因此您也必须在 -- 后包含这些默认位置参数 (scrapy tests)

tox -- scrapy tests -x  # stop after first failure

您还可以使用 pytest-xdist 插件。例如，要在 Python 3.10 的 tox 环境中使用所有 CPU 内核运行所有测试

tox -e py310 -- scrapy tests -n auto

要查看覆盖率报告，请安装 coverage (pip install coverage) 并运行

coverage report

有关更多选项（如 html 或 xml 报告），请参阅 coverage --help 的输出。

编写测试

所有功能（包括新功能和错误修复）都必须包含一个测试用例来检查其是否按预期工作，因此，如果您希望您的补丁尽快被接受，请为您的补丁包含测试。

Scrapy 使用单元测试，这些测试位于 tests/ 目录中。它们的模块名称通常类似于它们正在测试的模块的完整路径。例如，项目加载器代码位于

scrapy.loader

它们的单元测试位于

tests/test_loader.py