为 Scrapy 贡献

重要

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

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

  • 关于Scrapy的博客。告诉全世界你是如何使用Scrapy的。这将有助于新来者提供更多的示例,并有助于 Scrapy 的项目增加其可见性。

  • 报告“问题跟踪器”中的错误和请求功能,尝试遵循下面“报告错误”中详述的指南。

  • 提交新功能和/或错误修复的补丁。请阅读 编码补丁Submitting patches 以获取有关如何编写和提交补丁的详细信息。

  • 加入 Scrapy subreddit 分享你对如何改善垃圾的想法。我们总是乐于接受建议。

  • 回答一些 Scrapy 的问题 Stack Overflow .

报告错误

注解

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

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

  • 检查 FAQ 首先看看你的问题是否在一个众所周知的问题中得到解决

  • 如果你有一个关于报废使用的一般性问题,请在 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
    
  • 如果要删除不推荐使用的代码,请首先确保自引入不推荐使用的版本以来至少已经过了1年(12个月)。看到了吗 弃用政策 .

提交修补程序

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

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

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

有时候,为了解决某个问题,你需要解决一些问题。通常拉取请求的方向是正确的,但是变更是由无用的维护人员请求的,而原始的请求请求作者没有时间处理它们。在本例中,请考虑使用这个请求:打开一个新的请求,其中包含来自原始请求的所有提交,以及处理所引发问题的其他更改。这样做很有帮助;只要原著作者通过保持承诺而得到认可,就不会被认为是粗鲁的。

您可以通过运行 git fetch upstream pull/$PR_NUMBER/head:$BRANCH_NAME_TO_CREATE (将“上游”替换为Scrapy存储库的远程名称, $PR_NUMBER 带有拉请求的ID,以及 $BRANCH_NAME_TO_CREATE 包含要在本地创建的分支的名称)。另请参见:https://help.github.com/en/github/collaborating with issues and pull requests/checking out pull requests local#修改-本地非活动的请求。

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

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

编码风格

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

  • 除非另有规定,遵循 PEP 8 .

  • 如果可以提高代码的可读性,那么使用长度超过79个字符的行是可以的。

  • 不要把你的名字写在你贡献的代码中;git提供了足够的元数据来识别代码的作者。看到了吗https://help.github.com/en/github/using-git/setting-your-username-in-git安装说明。

文档策略

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

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

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

包含新功能或修改功能的文档更新必须使用Sphinx的 versionaddedversionchanged 指令。使用 VERSION 作为版本,我们将在相应版本发布之前用实际版本替换它。当我们发布一个新的主要或次要版本的Scrapy,我们删除这些指令,如果它们超过3年。

必须删除有关不推荐使用的功能的文档,因为这些功能已弃用,这样新的读者就不会碰到它。新的折旧和折旧删除记录在 release notes .

测验

测试是使用 Twisted unit-testing framework . 运行测试需要 tox .

运行试验

要运行所有测试:

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 py36,py38 -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

To see coverage report install coverage (pip install coverage) and run:

coverage report

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

写作测试

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

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

scrapy.loader

他们的单元测试在:

tests/test_loader.py