究竟什么被认为是图书馆箱子的重大变化? [英] What exactly is considered a breaking change to a library crate?

问题描述

Rust crate 使用语义版本控制.因此，每个具有重大更改的版本都应该导致主要版本的提升.破坏性更改通常被认为可能会破坏下游 crate(编码取决于相关库).

Rust crates use Semantic Versioning. As a consequence, each release with a breaking change should result in a major version bump. A breaking change is commonly considered something that may break downstream crates (code the depends on the library in question).

然而，在 Rust 中，很多东西都有可能破坏下游的 crate.例如，更改(仅包括添加到)公共符号集可能是一个重大更改，因为下游 crate 可以使用 glob-imports(use foo::*;) 将我们库的符号拉入它们的命名空间.因此，添加符号也可以破坏依赖包；请参阅此示例.

However, in Rust a whole lot has the potential of breaking downstream crates. For example, changing (including merely adding to) the set of public symbols is possibly a breaking change, because downstream crates can use glob-imports (use foo::*;) to pull symbols of our library into their namespace. Thus, adding symbols can break dependent crates as well; see this example.

同样，更改(添加或更改版本)我们 的依赖项集可能会破坏下游构建.您还可以想象下游 crate 依赖于我们公共类型之一的特定大小.这很少(如果有的话)有用；我只想表明:只要下游板条箱足够努力，一切都可能是一个突破性的变化.

Similarly, changing (adding or changing the version) the set of our dependencies can break downstream builds. You can also imagine that the downstream crate relies on a specific size of one of our public types. This is rarely, if at all, useful; I just want to show: everything could be a breaking change, if only the downstream crate tries hard enough.

是否有任何指导方针?究竟什么被认为是重大更改，什么不是(因为它被认为是用户的错")?

推荐答案

有一个关于这个主题的 Rust RFC:RFC 1105:API 演进.它适用于任何 Rust 库项目，它涵盖了所有类型的更改(不仅仅是破坏性更改)以及它们如何影响语义版本控制.我将尝试总结 RFC 中的关键点，以免此答案成为仅链接的答案.:)

There is a Rust RFC on this subject: RFC 1105: API Evolution. It's applicable to any Rust library project, and it covers all kinds of changes (not just breaking changes) and how they impact semantic versioning. I'll try to summarize the key points from the RFC in order to not make this answer a link-only answer. :)

RFC 承认对库的几乎任何更改都可能导致客户端突然停止编译.因此，它定义了一组主要变化，需要一个主要版本号的碰撞，以及一组次要变化，它需要一个次要版本的碰撞数字;并非所有重大更改都是重大更改.

The RFC acknowledges that pretty much any change to a library can cause a client to suddenly stop compiling. As such, it defines a set of major changes, which require a bump of the major version number, and a set of minor changes, which require a bump of the minor version number; not all breaking changes are major changes.

微小更改的关键属性是必须有一种方法使客户端可以通过稍微更改其源代码来提前避免损坏(例如，将全局导入更改为非全局导入，使用 UFCS 消除模棱两可的调用等)，以使代码与更改之前的版本以及包含更改的版本(假设它是次要版本)兼容.微小的更改也不得迫使下游的 crate 进行重大的破坏性更改以解决破损问题.

The key attribute of a minor change is that there must be a way that clients can avoid the breakage in advance by altering slightly their source code (e.g. change a glob import to a non-glob import, disambiguate an ambiguous call with UFCS, etc.) in such a way that the code is compatible with the version prior to the change and with the version that includes the change (assuming that it's a minor release). A minor change must also not force downstream crates to make major breaking changes in order to resolve the breakage.

RFC 中定义的主要更改(截至 commit 721f2d74) 是:

The major changes defined in the RFC (as of commit 721f2d74) are:

• 将您的项目从与稳定编译器兼容切换为仅与夜间编译器兼容.
• 重命名、移动或删除模块中的任何公共项目.
• 当所有当前字段都是公共字段时，将私有字段添加到结构中.
• 向没有私有字段的结构添加公共字段.
• 向枚举添加新变体.
• 向枚举变体添加新字段.
• 向特征添加非默认项.
• 对特征项签名的任何重大更改.
• 实施基础现有类型的特征.
• 收紧现有类型参数的界限.
• 向函数添加或删除参数.
• 未在 RFC 中列为次要更改的任何其他重大更改.

RFC 中定义的细微变化(从 commit 721f2d74，除非指定，否则会中断)是:

The minor changes defined in the RFC (as of commit 721f2d74, breaking unless specified) are:

• 改变在板条箱上使用 Cargo 功能.
• 在模块中添加新的公共项目.
• 在结构中至少有一个私有字段时添加或删除私有字段(更改前后)[不破坏].
• 将包含所有私有字段(至少有一个字段)的元组结构转换为普通结构，反之亦然.
• 向特征添加默认项.
• 向特征添加默认类型参数[不破坏].
• 在现有类型上实现任何非基本特征.
• 将任何项目添加到固有的impl.
• 更改函数的未记录行为.
• 放松对现有类型参数的限制[不破坏].
• 向类型或特征添加默认类型参数[不破坏].
• 通过用默认为先前类型的新类型参数替换其类型来概括现有结构或枚举字段[中断直到 问题 27336 已修复].
• 向现有函数引入新的类型参数.
• 通过用可实例化为先前类型的新类型参数替换类型来泛化现有函数的参数或返回类型.
• 引入新的 l​​int 警告/错误.

请参阅RFC用于解释和示例.

See the RFC for explanations and examples.

这篇关于究竟什么被认为是图书馆箱子的重大变化?的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！