版本控制

版本变更

Polars 遵循 语义化版本控制 规范：

• 重大变更会导致主要版本号增加（1.0.0, 2.0.0, ...）
• 新功能和性能改进导致次要版本增加（1.1.0, 1.2.0, ...）
• 其他更改会导致补丁版本增加（1.0.1, 1.0.2, ...）

重大变更政策

Polars 非常重视向后兼容性，但如果改变能带来更好的产品，我们也不害怕做出改变。

哲学

我们并不总是第一次就能做对。我们在过程中学习，并从用户那里获得反馈。有时，我们太急于推出新功能，而没有充分考虑所有可能的影响。

如果发生这种情况，我们会纠正错误并引入一个重大变更。大多数情况下，这并不严重。用户会收到一个弃用警告，他们在代码库中进行快速搜索和替换，就这样解决了。

有时，我们会遇到一个问题，需要用户付出更多努力来修复。查询引擎的更改可能会严重影响数据管道中的假设。我们不会轻易做出这样的更改，但如果我们认为这会使Polars变得更好，我们就会做出这些更改。

摆脱过去的失误对于保持Polars向前发展至关重要。我们知道用户需要花费时间和精力来跟上新版本的发布，但最终，让Polars成为最好的产品对每个人都有利。

什么构成了破坏性变更

当公共API的现有组件被更改或移除时，就会发生重大变更。

如果一个特性在API参考中有文档记录，那么它就是公共API的一部分。

破坏性变更的示例：

• 已弃用的函数或方法已被移除。
• 参数的默认值已更改。
• 由于查询引擎的更改，查询结果已发生变化。

不被视为破坏性更改的示例：

• 一个未记录的函数被移除。
• 公共类的模块路径已更改。
• 向现有方法添加了一个可选参数。

Bug修复不被视为破坏性更改，即使它可能会影响一些用户的工作流程。

不稳定的功能

公共API的某些部分被标记为不稳定。您可以通过API参考中的警告或当配置选项warn_unstable激活时发出的警告来识别此功能。功能被标记为不稳定的原因有很多：

• 我们不确定确切的API。名称、函数签名或实现可能会在未来发生变化。
• 该功能尚未经过广泛测试。在实际使用场景中可能会出现错误。
• 该功能尚未与完整的Polars API良好集成。您可能会发现它在某些情况下有效，但在其他情况下无效。

将功能作为不稳定版本发布，使我们能够从在实际场景中使用Polars的用户那里收集重要的反馈。这有助于我们在最终批准之前进行微调。只对稳定、经过充分测试的功能感兴趣的用户可以避免使用API的这一部分。

标记为不稳定的功能可能会在任何时候发生变化，而不被视为破坏性更改。

弃用警告

如果我们决定引入一个破坏性更改，现有的行为如果可能的话将被弃用。例如，如果我们选择重命名一个函数，新函数将与旧函数一起添加，使用旧函数将导致弃用警告。

并非所有的更改都能很好地被弃用。对查询引擎的更改可能会对API的大部分产生影响。此类更改将不会发出警告，但会包含在变更日志和迁移指南中。

弃用期

通常，弃用的功能在弃用发生后的两个重大版本中会被移除。 例如，在版本1.2.3中弃用的函数将在版本2.0.0中保留，并在版本3.0.0中被移除。

此规则的一个例外是在重大发布中引入的弃用。这些将在下一个重大发布中强制执行。例如，在版本2.0.0中弃用的函数将在版本3.0.0中移除。

这意味着如果你的程序没有引发任何弃用警告，升级到下一个主要版本应该是相对安全的。由于重大变更发布大约每六个月发生一次，这为你提供了六到十二个月的时间来适应任何即将到来的重大变更。

在某些情况下，我们可能会决定调整弃用期。 如果保留弃用的功能阻碍了Polars的其他改进，我们可能会将弃用期缩短为一个重大发布版本。这将在警告信息中提到。如果弃用影响到许多用户，我们可能会延长弃用期。

发布频率

Polars 没有固定的发布计划。我们觉得有新的、有价值的东西可以提供给用户时，就会发布新版本。实际上，大约每两周会发布一个新的次要版本。

重大发布

随着时间的推移，会出现一些问题，需要进行重大更改来解决。当积累足够多的问题时，我们会发布一个重大更新版本。

到目前为止，重大版本的发布大约每三到六个月发生一次。随着Polars变得更加稳定，重大变更的频率和严重性将继续减少。从这一点来看，我们预计新的主要版本大约每六个月发布一次。