为 Scrapy 贡献

重要

请仔细检查您是否正在阅读本文档的最新版本,网址为https://docs.scrapy.org/en/master/contributing.html

有很多方法可以为Scrapy做出贡献。 这里是其中的一些:

  • 关于Scrapy的博客。告诉全世界你是如何使用Scrapy的。这将有助于新来者提供更多的示例,并有助于 Scrapy 的项目增加其可见性。
  • 报告“问题跟踪器”中的错误和请求功能,尝试遵循下面“报告错误”中详述的指南。
  • 提交新功能和/或错误修复的补丁。请阅读 编码补丁Submitting patches 以获取有关如何编写和提交补丁的详细信息。
  • 加入 Scrapy subreddit 分享你对如何改善垃圾的想法。我们总是乐于接受建议。
  • 回答一些琐碎的问题 Stack Overflow .

报告错误

注解

请报告安全问题 only 发送至scrapy-security@googlegroups.com。这是一个私人列表,只对受信任的垃圾开发者开放,其档案不公开。

写得好的bug报告非常有用,因此在报告新bug时,请记住以下指导原则。

  • 检查 FAQ 首先看看你的问题是否在一个众所周知的问题中得到解决
  • 如果您对 Scrapy 的使用有一般性问题,请在 Stack Overflow (使用“报废”标签)。
  • 检查`open issues`_以查看是否已报告该问题。 如果有,请不要关闭该报告,但请检查故障单历史记录和注释。 如果你有其他有用的信息,请发表评论,或者考虑:ref:`发送拉动请求<writing-patches>`并修复。
  • 搜索 scrapy-users 列表和 Scrapy subreddit 看看是否在那里讨论过,或者你不确定你所看到的是否是一个bug。您也可以在``#scrapy`` IRC频道中询问。
  • 写 完整、可复制、特定的错误报告. 测试用例越小越好。请记住,其他开发人员不会让您的项目复制该bug,因此请包括复制该bug所需的所有相关文件。例如,例如,请参阅StackOverflow关于创建“最小,完整且可验证的示例”的指南,该指南展示了该问题。
  • 提供一个完整的可复制示例的最棒的方法是发送一个pull请求,该请求将一个失败的测试用例添加到Scrapy测试套件中(请参见 提交修补程序 )即使你不打算自己解决这个问题,这也是有帮助的。
  • 包括的输出 scrapy version -v 因此,开发人员在您的bug上准确地知道它发生在哪个版本和平台上,这通常对复制它非常有帮助,或者知道它是否已经被修复了。

编码补丁

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

写得好的补丁应该:

  • 包含特定更改所需的最小代码量。小补丁更容易查看和合并。因此,如果您进行了多个更改(或错误修复),请考虑为每个更改提交一个补丁。不要将多个更改折叠为单个修补程序。对于较大的更改,请考虑使用修补程序队列。

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

  • 包括一个(或多个)测试用例,检查修复的错误或添加的新功能。请参阅下面的“编写测试”。

  • 如果要添加或更改公共(文档化)API,请在同一补丁中包含文档更改。请参阅下面的“文档策略”。

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

    要查看是否正确跳过了您的私有API,请生成文档覆盖率报告,如下所示:

    tox -e docs-coverage
    

提交修补程序

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

记住解释什么是固定的或新的功能(它是什么,为什么需要它,等等)。您包含的信息越多,核心开发人员就越容易理解和接受您的补丁。

您也可以在创建补丁之前讨论新的功能(或bug修复),但是准备好一个补丁来说明您的论点并表明您已经在主题中添加了一些额外的思想总是很好的。一个好的起点是在Github上发送一个拉请求。它可以很简单地说明您的想法,并将文档/测试留到稍后,在这个想法被验证和证明是有用的之后。或者,您可以在 Scrapy subreddit 先讨论你的想法。

有时,对于您想要解决的问题,有一个现有的请求请求,由于某种原因而停止。通常拉请求的方向是正确的,但更改是由 Scrapy 维护人员请求的,而原始拉请求作者没有时间处理它们。在这种情况下,考虑接受这个拉请求:打开一个新的拉请求,其中包含来自原始拉请求的所有提交,以及解决所提出问题的其他更改。这样做有很大的帮助;一旦原作者被承认遵守了自己的承诺,就不会被认为是不礼貌的。

您可以通过运行``git fetch upstream pull / $ PR_NUMBER / head:$ BRANCH_NAME_TO_CREATE``将现有的pull请求拉到本地分支(用scrapy存储库的远程名称替换'upstream',$ PR_NUMBER 拉取请求的ID,以及“$ BRANCH_NAME_TO_CREATE”,其中包含您要在本地创建的分支的名称。 另见:https://help.github.com/articles/checking-out-pull-requests-locally/#modifying-an-inactive-pull-request-locally。

在编写Github Pull请求时,请尽量保持标题简短但具有描述性。例如,对于bug 411:“如果启动请求中出现异常,则scrapy将挂起”首选“当启动请求中出现异常时修复挂起”(而不是“修复为411”)。完整的标题使浏览问题跟踪器变得容易。

最后,试着保持审美的变化( PEP 8 合规性、未使用的进口删除等)与功能更改分开提交。这将使pull请求更容易审查,更容易合并。

编码风格

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

  • 除非另有规定,遵循 PEP 8 .
  • 如果它提高了代码的可读性,那么使用超过80个字符的行是可以的。
  • 不要在您贡献的代码中输入您的名字;Git提供了足够的元数据来标识代码的作者。有关安装说明,请参阅https://help.github.com/articles/setting-your-username-in-git/。

文档策略

对于API成员(类、方法等)的参考文档,请使用docstring并确保sphinx文档使用 autodoc 用于拉取docstrings的扩展。API参考文档应遵循docstring惯例 (PEP 257 )并且对IDE友好:简短,直截了当,它可能提供简短的示例。

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

在任何情况下,如果文档字符串中包含某些内容,请使用 autodoc 扩展名,用于将docstring拉入文档,而不是在 docs/ 目录。

测验

测试是使用`Twisted unit-testing framework`_实现的,运行测试需要`tox`_。

运行试验

确保你最近有足够的 tox 安装:

tox --version

如果您的版本早于1.7.0,请先更新:

pip install -U tox

要运行所有测试,请转到Scrapy源代码的根目录并运行:

tox

要运行特定的测试(比如``tests / test_loader.py``),请使用:

tox -- tests/test_loader.py

在特定的 tox 环境,使用 -e <name> 环境名称来自 tox.ini . 例如,要使用python 3.6运行测试,请使用:

tox -e py36

还可以指定以逗号分隔的环境列表,并使用 tox’s parallel mode 要在多个环境上并行运行测试,请执行以下操作:

tox -e py27,py36 -p auto

将命令行选项传递到 pytest, 在后面添加 -- 在你的电话里 tox. 使用 -- 重写中定义的默认位置参数 tox.ini ,因此必须包含这些默认位置参数 (scrapy tests )之后 -- 也::

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

您也可以使用 pytest-xdist 插件。例如,在python 3.6上运行所有测试 tox 使用所有CPU核心的环境:

tox -e py36 -- scrapy tests -n auto

要查看覆盖率报告,请安装`coverage`_(pip install coverage)并运行:

coverage report

有关html或xml报告等更多选项,请参阅``coverage --help``的输出。

写作测试

所有功能(包括新功能和错误修复)都必须包含一个测试用例,以检查它是否按预期工作,因此如果您希望补丁能够更快地被接受,请包含对它们的测试。

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

scrapy.loader

他们的单元测试在:

tests/test_loader.py