Question

我们非常欢迎和感谢您的贡献。每一点帮助都很重要，所以不要犹豫！

目录

• 贡献开始

  • 功能请求和反馈

  • 报告错误

  • 修复错误

  • 实现功能

  • 编写文档

  • 向pytest dev提交插件

  • 准备拉取请求

  • 加入开发团队

  • 下一个补丁版本的后移植错误修复

  • 处理过时的问题/pr

  • 结案问题

功能请求和反馈

你喜欢比重测试吗？在Twitter或博客上分享一些爱！

我们还想听听你的建议和建议。随意 submit them as issues 还有：

• 详细解释他们应该如何工作。

• 尽量缩小范围。这将使其更容易实现。

报告错误

在中报告pytest的错误 issue tracker .

如果您报告错误，请包括：

• 您的操作系统名称和版本。

• 有关本地设置的任何详细信息，可能有助于排除故障，特别是python解释器版本、已安装的库和pytest版本。

• 复制错误的详细步骤。

如果您可以编写一个当前失败但应该通过（xfail）的演示测试，那么这也是一个非常有用的提交，即使您不能修复bug本身。

修复错误

看看 GitHub issues for bugs .

Talk 以了解如何修复特定的bug。要指示您将要处理某个特定问题，请在该特定问题上添加相应的注释。

别忘了检查你最喜欢的插件的问题跟踪程序！

实现功能

看看 GitHub issues for enhancements .

Talk 向开发人员了解如何实现特定功能。

编写文档

pytest总是可以使用更多的文档。到底需要什么？

• 更多补充文件。你有没有发现不清楚的东西？

• 文档翻译。我们现在只有英语。

• 文档字符串。它们永远不会太多。

• 博客文章、文章等等——他们都非常感激。

您还可以直接在Github Web界面中编辑文档文件，而无需使用本地副本。这对于小的修复是很方便的。

注解

使用以下命令在本地生成文档：

$ tox -e docs

生成的文档应在 doc/en/_build/html ，其中 en 表示文档语言。

Pytest有一个API引用，它在很大程度上是 generated automatically 从文档项的docstring。py测试 Sphinx docstring format . 例如：

def my_function(arg: ArgType) -> Foo:
    """Do important stuff.

    More detailed info here, in separate paragraphs from the subject line.
    Use proper sentences -- start sentences with capital letters and end
    with periods.

    Can include annotated documentation:

    :param short_arg: An argument which determines stuff.
    :param long_arg:
        A long explanation which spans multiple lines, overflows
        like this.
    :returns: The result.
    :raises ValueError:
        Detailed information when this can happen.

    .. versionadded:: 6.0

    Including types into the annotations above is not necessary when
    type-hinting is being used (as in this example).
    """

向pytest dev提交插件

核心的pytest开发，一些插件和支持代码发生在生活在 pytest-dev 组织：

• pytest-dev on GitHub

所有pytest dev contributors团队成员都具有对所有包含的存储库的写访问权。pytest核心和插件通常是使用 pull requests 到各自的存储库。

的目标 pytest-dev 组织是：

• 有一个流行的Pytest插件的中心位置

• 共享一些维护责任（如果维护人员不再希望维护插件）

您可以通过订阅 pytest-dev mail list 并编写一封指向现有Pytest插件存储库的邮件，其中必须包含以下内容：

• 包含 pytest- 前缀名、版本号、作者、简短和详细描述。

• 一 tox configuration 用于运行测试，使用 tox .

• 一 README 描述如何使用插件以及它在哪个平台上运行。

• 一 LICENSE 包含许可信息的文件，其打包元数据中包含匹配的信息。

• 用于错误报告和增强请求的问题跟踪程序。

• 一 changelog .

如果没有参与者强烈反对，并且两个同意，那么可以将存储库传输到 pytest-dev 组织。

下面是存储库传输通常是如何进行的（使用名为 joedoe/pytest-xyz 例如：

• joedoe 将存储库所有权转移到 pytest-dev 管理员 calvin .

• calvin 创造 pytest-xyz-admin 和 pytest-xyz-developers 团队，邀请 joedoe 兼而有之 保持器 .

• calvin 将存储库传输到 pytest-dev 并配置团队访问：

  • pytest-xyz-admin 管理员 访问；

  • pytest-xyz-developers 写 访问；

这个 pytest-dev/Contributors 团队拥有对所有项目的写访问权，并且每个项目管理员都在其中。我们建议每个插件至少有三个人有权发布到pypi。

知识库所有者可以放心，没有 pytest-dev 管理员将永远不会发布您的存储库或以任何方式取得所有权，除非在极少数情况下，有人经过数月的联系尝试后没有反应。如前所述，目标是共享维护并避免 放弃插件 。

准备拉取请求

短版

1. 复刻存储库。

2. 启用并安装 pre-commit 确保遵循样式指南和代码检查。

3. 跟随 PEP-8 命名和 black 用于格式化。

4. 使用运行测试 tox ：：

   tox -e linting,py37
   

   上面的测试环境通常足以在本地覆盖大多数情况。

5. 写一篇 changelog 条目： changelog/2574.bugfix.rst ，使用问题ID号和 feature ， improvement ， bugfix ， doc ， deprecation ， breaking ， vendor 或 trivial 对于问题类型。

6. 除非您的更改是一个琐碎的或文档修复（例如，一个小部分的拼写错误或改写），请将您自己添加到 AUTHORS 按字母顺序归档。

长版

什么是 拉请求 ？它将通知项目的核心开发人员您要查看和合并的更改。拉取请求存储在 GitHub servers . 一旦您发送了一个请求，我们就可以讨论它的潜在修改，甚至在以后添加更多的提交。有一个关于拉请求如何在 GitHub Help Center .

下面是一个简单的概述，其中包含pytest特定的位：

1. 叉 pytest GitHub repository . 使用起来很好 pytest 作为您的fork存储库名称，因为它将位于您的用户之下。

2. 使用在本地复制您的复刻 git 创建一个分支：

   $ git clone git@github.com:YOUR_GITHUB_USERNAME/pytest.git
   $ cd pytest
   # now, create your own branch off "master":
   
       $ git checkout -b your-bugfix-branch-name master
   

   既然我们有 大、小、微 版本号、错误修复通常会在微版本中发布，而特性则会在小版本中发布，而不兼容的更改则会在主要版本中发布。

   如果您需要有关Git的帮助，请遵循以下快速入门指南：https://git.wiki.kernel.org/index.php/quick start

3. 安装 pre-commit 它的钩子在pytest repo上：

   $ pip install --user pre-commit
   $ pre-commit install
   

   之后 pre-commit 将在您提交时运行。

   https://pre-commit.com/ is a framework for managing and maintaining multi-language pre-commit hooks to ensure code-style and code formatting is consistent.

4. 安装托克斯

   tox用于运行所有测试，并将自动设置virtualenvs以在中运行测试。（将隐式使用http://www.virtualenv.org/en/latest/）：

   $ pip install tox
   

5. 运行所有测试

   您需要在系统中提供python 3.7。现在运行测试就像发出以下命令一样简单：

   $ tox -e linting,py37
   

   此命令将通过 tox 工具对python 3.7运行测试，并执行 lint 编码样式检查。

6. 现在可以编辑本地工作副本，并根据需要再次运行测试。请按照PEP-8命名。

   您可以将不同的选项传递给 tox . 例如，要在python 3.7上运行测试并将选项传递给pytest（例如，失败时输入pdb），可以执行以下操作：

   $ tox -e py37 -- --pdb
   

   或者只在Python3.7上的特定测试模块中运行测试：

   $ tox -e py37 -- testing/test_config.py
   

   承诺时， pre-commit 必要时将重新格式化文件。

7. 如果不使用 tox 您更喜欢直接运行测试，然后我们建议创建一个虚拟环境，并使用 testing 额外：：

   $ python3 -m venv .venv
   $ source .venv/bin/activate  # Linux
   $ .venv/Scripts/activate.bat  # Windows
   $ pip install -e ".[testing]"
   

   然后，您可以编辑文件并正常运行pytest:：

   $ pytest testing/test_config.py
   

8. 在中创建新的变更日志条目 changelog . 该文件应命名为 <issueid>.<type>.rst 在哪里 发行股票 是与变更相关的问题编号，以及 type 是其中之一 feature ， improvement ， bugfix ， doc ， deprecation ， breaking ， vendor 或 trivial . 如果更改不影响pytest的记录行为，则可以跳过创建changelog条目。

9. 增加你自己 AUTHORS 如果还没有，按字母顺序归档。

10. 一旦您的测试通过，并且您对您的更改感到满意，就提交并推送：

    $ git commit -a -m "<commit message>"
    $ git push -u
    

11. 最后，使用以下数据通过Github网站提交请求：

    head-fork: YOUR_GITHUB_USERNAME/pytest
    compare: your-branch-name
    
    base-fork: pytest-dev/pytest
    base: master
    

写作测试

为插件或pytest本身编写测试通常使用 pytester fixture 作为 黑匣子 测试。

例如，为了确保简单的测试通过，您可以编写：

def test_true_assertion(pytester):
    pytester.makepyfile(
        """
        def test_foo():
            assert True
    """
    )
    result = pytester.runpytest()
    result.assert_outcomes(failed=0, passed=1)

或者，可以根据使用的术语的实际输出进行检查。 glob-like 表达：

def test_true_assertion(pytester):
    pytester.makepyfile(
        """
        def test_foo():
            assert False
    """
    )
    result = pytester.runpytest()
    result.stdout.fnmatch_lines(["*assert False*", "*1 failed*"])

当选择一个文件在哪里写一个新的测试时，看看现有的文件，看看是否有一个文件看起来很合适。例如，关于 --lf 选项应进入 test_cacheprovider.py ，考虑到此选项是在 cacheprovider.py . 如果有疑问，可以用你最好的猜测打开一个公关，我们可以通过代码来讨论这个问题。

加入开发团队

任何成功通过拉取请求（不需要开发团队额外的工作来合并）的人，如果愿意，他们自己将获得提交访问权限（如果我们忘记请求，请发送友好的提醒）。这并不意味着你的贡献工作流程有任何改变：每个人都要经历相同的请求请求和评审过程，除非已经被批准，否则没有人合并他们自己的请求。但是，这意味着您可以更全面地参与开发过程，因为您可以在审阅其他参与者的请求后自行合并它们。

下一个补丁版本的后移植错误修复

Pytest每隔几周或几个月发布一次特性。在这两者之间，补丁版本是对以前的功能版本进行的，只包含错误修复。bug修复通常修复回归，但可能是在下一个特性发布之前应该到达用户的任何更改。

例如，假设最新版本是1.2.3，并且您希望在1.2.4中包含一个错误修复（检查https://github.com/pytest-dev/pytest/releases对于实际的最新版本）。具体步骤如下：

1. 首先，确保错误被修复 master 分支，具有常规的拉取请求，如上所述。例外情况是，如果错误修复不适用于 master 不再。

2. git checkout origin/1.2.x -b backport-XXXX #在这里使用主公关号码

3. 在PR上找到merge commit，在 合并 消息，例如：

   nicodedemus将commit 0f8b462合并到pytest中-德夫：主人

4. git cherry-pick -x -m1 REVISION #使用上面找到的版本 (0f8b462 ）

5. 打开公关目标 1.2.x ：

   • 在邮件前面加上前缀 [1.2.x] .

   • 删除PR body，它通常包含一个重复的commit消息。

谁负责后台工作

如上所述，bug应该首先被修复 master （除非在极少数情况下bug只在以前的版本中出现）。那么，谁应该执行上面描述的后端口过程？

1. 如果这个bug是由核心开发人员修复的，那么核心开发人员的主要职责就是进行后台处理。

2. 然而，通常合并是由另一个维护人员来完成的，在这种情况下，如果他们有时间的话，最好执行后端口过程。

3. 对于非维护人员提交的bug，预期核心开发人员将执行后台处理，通常是合并PR的那个 master .

4. 如果一个非维护人员注意到一个bug master 但是没有被后传（由于维护人员忘记应用 需要后场 标签，或只是简单地错过它），他们也欢迎打开一个公关与后端口。程序很简单，对项目的维护非常有帮助。

以上所有的都不是规则，只是一些指导/建议，我们应该期待什么样的后台。

处理过时的问题/pr

陈腐的问题/pr是那些pytest贡献者提出问题/修改，而作者在一段时间后还没有抽出时间来回答/实现它们，或者讨论只是因为人们似乎失去了兴趣而消失了。

人们不回答问题或不实现请求的更改有很多原因：他们可能会忙起来，失去兴趣，或者干脆忘记了，但事实上，这在开源软件中非常常见。

pytest团队非常欣赏每一个问题和请求请求，但是作为一个高容量的项目，每天都有许多问题和请求被提交，我们试图通过定期关闭它们来减少过时问题和pr的数量。当一个问题/拉取请求以这种方式关闭时，这绝不是对问题/拉请求正在处理的主题的否定，而是我们清理队列，使维护人员的工作更易于管理的一种方法。如果有意义，提交者可以在自己的时间内重新打开问题/请求。

何时关闭

以下是一些一般规则，维护人员使用这些规则来决定何时关闭问题/pr，因为没有不活动：

• 标记的问题 question 或 needs information ：停用14天后关闭。

• 标记的问题 proposal ：六个月后关闭。

• 拉请求：一个月后，考虑ping作者，更新链接问题，或者考虑关闭。对于接近完成的请求，团队应该考虑完成并合并它。

以上是 不是硬性规定 ，但仅仅 指导方针 ，可以是（而且通常是！）逐案审查。

关闭拉动请求

在结束拉取请求时，需要确认提交请求的人所显示的时间、精力和兴趣。如前所述，团队的目的并不是完全消除暂停的拉取请求，而只是为了清理队列，因此，在关闭过时的拉请求时，可以发出下面这样的消息：

嗨<contributor>，

首先，我们要感谢您为此付出的时间和努力，pytest团队对此深表感谢。

不过，我们注意到你更新此公关已经有一段时间了。pytest是一个高活动性的项目，每天都有许多问题/pr被打开，因此我们的维护人员很难跟踪哪些pr已经准备好合并、评审或者需要更多的关注。

因此，出于这些原因，我们认为现在最好关闭公关，但我们的唯一目的是清理我们的队列，这绝不是拒绝您的更改。我们仍然鼓励您在准备好返回时重新打开此公关（只需点击按钮）。

再次感谢您抽出时间来做这件事，并希望您能在以后的时间回到这件事！

<再见>

结案问题

当提交拉取请求以解决问题时，请添加以下文本： closes #XYZW 对PR描述和/或提交（其中 XYZW 是问题编号）。见 GitHub docs 更多信息。

当问题是由于用户错误（例如对功能的误解）引起的时，请礼貌地向用户解释为什么提出的问题实际上不是问题，如果他们没有进一步的问题，请他们关闭问题。如果原始请求者没有响应，则将按照本节中的描述处理该问题 Handling stale issues/PRs 上面。