向后兼容策略

pytest正在积极地发展,是一个经过几十年酝酿的项目,我们不断学习新的更好的结构来表达关于测试的不同细节。

当我们实现这些修改时,我们试图确保一个简单的过渡,不想给我们的用户和社区/插件作者带来不必要的干扰。

到目前为止,pytest考虑了多种类型的向后兼容性转换:

  1. 琐碎的:简单地转换为新机制的API,不会引起有问题的更改。

    我们试图无限期地支持这些机制,同时通过文档鼓励用户切换到更新/更好的机制。

  2. 过渡:新旧API不冲突,我们可以通过使用警告来帮助用户过渡,同时在较长时间内支持两者。

    我们将只在主要版本中开始删除不推荐使用的功能(例如,如果我们在3.0版本中弃用某个功能,我们将在4.0版本中开始删除它),并将其保留至少两个次要版本(例如,如果我们在3.9和4.0版本中弃用某个功能,我们将在5.0版本中删除它,而不是在4.0版本中)。

    当折旧到期(例如4.0已发布)时,我们不会立即删除已弃用的功能,而是使用标准警告过滤器将其转换为 错误 默认情况下。这种方法明确地表明删除是迫在眉睫的,并且仍然给您时间将不推荐使用的特性转换为警告,而不是错误,以便在您自己的时间内处理它。在下一个次要版本(例如4.1)中,该特性将被有效地删除。

  3. 真正的破坏:只有当正常的过渡是不合理的不可持续的,并且会在几年内抵消重要的发展/特征时,才应该考虑。此外,应该限制在实际用户数量非常少的API(例如只影响一些插件),并且可以提前与社区协调。

    这些即将发生的变化的例子:

    • 移除 pytest_runtest_protocol/nextitem - #895

    • 重新排列节点树以包括 FunctionDefinition

    • 重新安排 SetupState #895

    真正的破损必须首先在包含以下内容的问题中公布:

    • 变更的详细说明

    • 理论基础

    • 对用户和插件作者的预期影响(示例 #895

    在没有困难之后 -1 在这个问题上,应该先提出概念验证请求。

    这个POC既是评估影响的协调点,也是提出过渡性解决方案的潜在灵感。

    在一段合理的时间之后,PR可以合并为一个新的主要版本。

    从POC到验收,PR必须包含: * Setup of deprecation errors/warnings that help users fix and port their code. If it is possible to introduce a deprecation period under the current series, before the true breakage, it should be introduced in a separate PR and be part of the current release stream. * 详细描述如何将代码移植到 doc/en/deprecations.rst .

历史

主要关注平滑过渡-站姿(6.0版之前)

在Pytest项目中,保持向后兼容性具有非常高的优先级。尽管多年来我们已经弃用了功能,但大多数功能仍然受到支持。Pytest中的所有不赞成都是因为已经出现了完成相同任务的更简单或更有效的方法,使得做事情的旧方法变得不必要。

在pytest 3.0版本中,我们引入了一个清晰的通信方案,当我们实际移除旧的总线连接时,我们会礼貌地要求您使用新的hostness,同时给您足够的时间来调整您的测试,或者在有正当理由保留不推荐的功能时提出问题。

为了传达更改,我们使用自定义的警告层次结构发出拒绝警告(请参见 内部Pytest警告 )可使用标准方法抑制这些警告: -W 命令行标志或 filterwarnings ini选项(请参见 捕获警告 ,但我们建议谨慎和临时使用,并在可能的情况下注意警告。

我们将只在主要版本中开始删除不推荐使用的功能(例如,如果我们在3.0版本中弃用某个功能,我们将在4.0版本中开始删除它),并将其保留至少两个次要版本(例如,如果我们在3.9和4.0版本中弃用某个功能,我们将在5.0版本中删除它,而不是在4.0版本中)。

当折旧到期(例如4.0已发布)时,我们不会立即删除已弃用的功能,而是使用标准警告过滤器将其转换为 错误 默认情况下。这种方法明确地表明删除是迫在眉睫的,并且仍然给您时间将不推荐使用的特性转换为警告,而不是错误,以便在您自己的时间内处理它。在下一个次要版本(例如4.1)中,该特性将被有效地删除。

折旧路线图

先前版本中当前已弃用和删除的功能可以在中找到 弃用和移除 .

我们使用里程碑和 deprecationremoval GitHub上的标签。