本文档介绍了OpenZeppelin Contracts库在不同版本之间的向后兼容性保证，包括API和存储布局的兼容性。文章解释了在patch和minor版本更新中通常会保持向后兼容，但某些情况下可能会有例外，特别是涉及到安全问题或draft状态的ERC标准时。同时提醒了override函数、struct结构体以及错误处理等方面需要注意的问题，并强调了major版本更新通常不保证兼容性。
向后兼容性
OpenZeppelin Contracts 使用语义化版本控制来传递其 API 和存储布局的向后兼容性。Patch 和 minor 更新通常是向后兼容的，但极少数情况下会有例外，如下文详述。应该假定 major 更新与以前的版本不兼容。在本页中，我们提供有关这些保证的详细信息。
API
在向后兼容的版本中，所有更改都应该是对内部实现细节的添加或修改。大多数代码应该能继续编译并按预期运行。此规则的例外情况如下所示。
安全
极少数情况下，patch 或 minor 更新会以破坏性的方式删除或更改 API，但这仅限于以前的 API 被认为是不安全的。这些重大更改将在变更日志和发行说明中注明，并与安全公告一起发布。
草案或预最终 ERC
尚未最终确定的 ERC 可能会以不兼容的方式更改。因此，我们避免在 ERC 最终确定之前发布其实现。对于已发布很长时间并且似乎不太可能更改的 ERC，会例外处理。在这种情况下，对 ERC 规范的重大更改在技术上仍然是可能的，因此这些实现以名为 draft-*.sol 的文件发布，以明确该条件。
Virtual & Overrides
此库中的几乎所有函数都是 virtual 的，但也有一些例外，但这并不意味着鼓励 overrides。有一部分函数设计为可以被 overridden。通过在此子集之外定义 overrides，你可能会依赖于内部实现细节。即使在这些情况下，我们也会努力保持向后兼容性，但这非常困难，并且很容易意外破坏。建议谨慎行事。
此外，由于 Solidity 认为继承函数存在歧义，因此一些 minor 更新可能会导致新的编译错误，例如“两个或多个基类定义了具有相同名称和参数类型的函数”或“需要指定 overridden contract”。这应该通过添加一个通过 super 调用该函数的override 来解决。
有关 virtual 和 overrides 的更多信息，请参见扩展合约。
Structs
带有下划线前缀的结构成员应被视为“private”，并且可能会在 minor 版本中中断。结构数据应仅通过库函数访问和修改。
Errors
除非另有说明，否则不应假定包含 reverts 的特定错误格式和数据是稳定的。
Major Releases
应该假定 major 版本不兼容。然而，如果合约的外部接口是标准化的，或者维护者认为更改它们会对生态系统造成重大压力，那么它们将保持兼容。
major 版本可能破坏的一个重要方面是“升级兼容性”，特别是存储布局兼容性。对于实时合约而言，从一个 major 版本升级到另一个版本永远是不安全的。
Storage Layout
Minor 和 patch 更新始终保持存储布局兼容性。这意味着可以从一个 minor 版本升级到另一个版本，而不会破坏存储布局。在某些情况下，升级时可能需要初始化新的状态变量，尽管我们预计这种情况不会经常发生。
我们建议使用 OpenZeppelin Upgrades Plugins or CLI 来确保升级的存储布局安全。
Solidity Version
编译合约所需的最低 Solidity 版本在 minor 和 patch 更新中将保持不变。在 minor 版本中引入的新合约可能会使用较新的 Solidity 功能，并需要更新版本的编译器。
← 与升级一起使用
访问控制 →
