为Scrapy做贡献¶

重要

请仔细确认您正在阅读本文档的最新版本，网址为 https://docs.scrapy.org/en/master/contributing.html

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

在问题跟踪器中报告错误和请求功能，尝试遵循下面报告错误中详述的指南。
提交新功能和/或错误修复的补丁。请阅读下面的编写补丁和提交补丁以了解如何编写和提交补丁。
关于Scrapy的博客。告诉世界你如何使用Scrapy。这将帮助新手获得更多示例，并帮助Scrapy项目提高其可见性。
加入Scrapy subreddit并分享您关于如何改进Scrapy的想法。我们始终欢迎建议。
在 Stack Overflow上回答Scrapy问题。

报告错误¶

注意

请仅将安全问题报告至 scrapy-security@googlegroups.com。这是一个仅对受信任的Scrapy开发者开放的私人列表，其存档不公开。

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

首先查看FAQ，看看您的问题是否在一个常见问题中得到解答
如果您对Scrapy的使用有一般性问题，请在 Stack Overflow 上提问（使用“scrapy”标签）。
检查开放问题，看看问题是否已经被报告。如果已经报告，请不要忽视报告，而是检查票证历史和评论。如果你有额外的有用信息，请留下评论，或者考虑发送一个拉取请求并提供修复。
搜索scrapy-users列表和Scrapy subreddit，看看是否已经在那里讨论过，或者如果你不确定你看到的是否是一个错误。你也可以在#scrapy IRC频道中询问。
编写完整、可复现、具体的错误报告。测试案例越小越好。请记住，其他开发者没有你的项目来复现错误，所以请包括复现错误所需的所有相关文件。例如，参见StackOverflow关于创建最小、完整且可验证的示例展示问题的指南。
提供完整可复现示例的最棒方式是发送一个拉取请求，该请求将失败的测试用例添加到Scrapy测试套件中（参见提交补丁）。即使您不打算自己修复问题，这也是有帮助的。
包括scrapy version -v的输出，这样处理你的错误的开发者可以确切知道它发生在哪个版本和平台上，这对于重现错误或知道它是否已经被修复通常非常有帮助。

编写补丁¶

Scrapy 有一系列 good first issues 和 help wanted issues 你可以参与。这些问题是一个很好的开始贡献 Scrapy 的方式。如果你是代码库的新手，你可能想要专注于文档或测试相关的问题，因为它们总是有用的，并且可以帮助你更熟悉项目。你还可以查看 Scrapy 的 test coverage 来了解哪些领域可能受益于更多的测试。

补丁写得越好，被接受的机会就越高，合并的速度也会越快。

编写良好的补丁应该：

包含特定更改所需的最少代码量。小的补丁更容易审查和合并。因此，如果您正在进行多个更改（或错误修复），请考虑为每个更改提交一个补丁。不要将多个更改合并到一个补丁中。对于大的更改，请考虑使用补丁队列。
通过所有单元测试。请参阅下面的运行测试。
包含一个（或多个）测试用例，用于检查已修复的错误或新增的功能。请参阅下面的编写测试。
如果您正在添加或更改一个公共（有文档记录的）API，请在同一补丁中包含文档更改。请参阅下面的文档政策。
如果你正在添加一个私有API，请向docs/conf.py的coverage_ignore_pyobjects变量添加一个正则表达式，以从文档覆盖率检查中排除新的私有API。

要查看您的私有API是否被正确跳过，请按以下方式生成文档覆盖率报告：
```
tox -e docs-coverage
```
如果你正在移除已弃用的代码，首先确保自引入弃用的版本发布以来至少已经过去了1年（12个月）。请参阅弃用政策。

提交补丁¶

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

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

你也可以在创建补丁之前讨论新功能（或错误修复），但准备好一个补丁来说明你的论点并表明你已经对这个主题进行了额外的思考总是好的。一个好的起点是在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://docs.github.com/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进行代码格式化。在pre-commit配置中有一个钩子，它会在每次提交前自动格式化你的代码。你也可以手动运行black，使用tox -e pre-commit。
不要在您贡献的代码中放入您的名字；git 提供了足够的元数据来识别代码的作者。请参阅 https://docs.github.com/en/get-started/getting-started-with-git/setting-your-username-in-git 以获取设置说明。

预提交¶

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

在你创建了Scrapy仓库分叉的本地克隆之后：

Install pre-commit.
在您本地克隆的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 并指定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 插件。例如，使用所有 CPU 核心在 Python 3.10 tox 环境中运行所有测试：

tox -e py310 -- scrapy tests -n auto

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

coverage report

查看 coverage --help 的输出以获取更多选项，如 html 或 xml 报告。

编写测试¶

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

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

scrapy.loader

他们的单元测试位于：

tests/test_loader.py