新版本发布和 API 稳定性 - OpenZeppelin 文档

本文档介绍了 OpenZeppelin Contracts 的发布计划和 API 稳定性保证。OpenZeppelin Contracts 遵循语义化版本控制,旨在每个月发布一个新的小版本,每几个月或一年发布一个新的主版本。API 稳定性意味着如果你的项目今天可以正常工作,它将继续这样做。新的合约和功能将在小版本中添加,但仅以向后兼容的方式添加。

你当前阅读的不是此文档的最新版本。5.x 是最新版本。

新版本发布和 API 稳定性

开发智能合约非常困难,有时会倾向于采取保守的依赖管理方式。然而,及时了解新版本发布也非常重要:这些版本可能包含错误修复,或弃用旧模式,转而支持更新、更好的实践。

在这里,我们将描述你应该期望何时发布新版本,以及这会如何影响你作为 OpenZeppelin Contracts 的用户。

发布计划

OpenZeppelin Contracts 遵循 语义化版本控制方案

小版本发布 (Minor Releases)

OpenZeppelin Contracts 的目标是每 1 或 2 个月发布一个新的小版本。

在发布周期的开始,我们决定要优先处理哪些问题,并将它们分配给 GitHub 上的一个里程碑。在接下来的五个星期里,我们将努力解决这些问题。

一旦里程碑完成,我们将发布一个功能冻结的候选版本 (release candidate)。候选版本的目的是让社区在实际发布之前审查新代码。如果发现重要问题,可能需要发布多个候选版本。在一个星期内没有对候选版本进行更改后,将发布新版本。

主版本发布 (Major Releases)

经过几个月或一年的时间,可能会发布一个新的主版本。这些版本没有固定的时间表,而是基于发布重大更改的需求,例如库的核心功能(例如 3.0 中的访问控制)的重新设计。由于我们重视稳定性,因此我们的目标是尽量减少这种情况的发生(预计主版本之间的间隔不少于六个月)。但是,当 Solidity 语言发生重大变化时,我们可能会被迫发布一个主版本。

API 稳定性

OpenZeppelin 2.0 发布版 中,我们承诺保持稳定的 API。我们旨在更精确地定义我们对 稳定API 的理解,以便库的用户能够理解这些保证,并确信他们的项目不会意外中断。

简而言之,API 保持稳定意味着 如果你的项目今天可以正常工作,那么它将继续正常工作。新的合约和功能将在小版本中添加,但仅以向后兼容的方式添加。

版本控制方案

我们遵循 SemVer,这意味着 API 可能会在主版本之间发生中断(这 不太经常发生)。

Solidity 函数

虽然函数的内部实现可能会更改,但它们的语义和签名将保持不变。它们的参数域不会更严格(例如,如果禁止传输值为 0 的值,它将保持禁止),也不会取消一般的状态限制(例如 whenPaused 修饰符)。

如果向合约添加新函数,它将以向后兼容的方式添加:它们的使用不是强制性的,并且它们不会以可能预见的方式破坏应用程序的方式扩展功能(例如,可以添加一个 internal 方法,以便更容易检索已可用的信息)。

internal

这不仅适用于 externalpublic 函数,而且适用于 internal 函数:许多合约旨在通过继承来使用它们(例如 PausablePullPayment、不同的 Roles 合约),因此通过调用这些函数来使用它们。同样,由于所有 OpenZeppelin Contracts 状态变量都是 private 的,因此只能通过这种方式访问它们(例如,要创建新的 ERC20 tokens,应该调用 _mint,而不是手动修改 totalSupplybalances)。

private 函数对其行为、用法或存在没有任何保证。

最后,有时语言的局限性会迫使我们例如将 internal 函数设置为应该是 private 的函数,以便以我们想要的方式实现功能。这些情况将得到充分的记录,并且正常的稳定性保证将不适用。

我们的一些 Solidity 库使用 struct 来处理不应直接访问的内部数据(例如 Roles)。Solidity 仓库中有一个 未解决的问题,要求提供一种语言功能来防止此类访问,但看起来它不会很快实现。因此,我们将使用前导下划线并标记所述 struct,以向用户明确其内容和布局 不是 API 的一部分。

事件

不会删除任何事件,并且它们的参数不会以任何方式更改。可以在更高版本中添加新事件,并且可以在新的、合理的情况下发出现有事件(例如,从 2.1 开始,ERC20 也在 transferFrom 调用时发出 Approval)。

Gas 成本

虽然通常会尝试降低使用 OpenZeppelin Contracts 的 gas 成本,但对此没有任何保证。特别是,用户不应假设在升级库版本时 gas 成本不会增加。

Bug 修复

为了修复 bug,可能需要打破 API 稳定性保证,我们将这样做。但是,不会轻易做出此决定,并且将探索所有选项以使更改尽可能不具有破坏性。在充分的情况下,可能导致不安全行为的合约或函数将被弃用而不是删除(例如 #1543#1550)。

Solidity 编译器版本

从 0.5.0 版本开始,Solidity 团队切换到更快的发布周期,每隔几周发布一个小版本(v0.5.0 于 2018 年 11 月发布,v0.5.5 于 2019 年 3 月发布),每隔几个月发布一个主要的、破坏性更改的版本(v0.6.0 于 2019 年 12 月发布,v0.7.0 于 2020 年 7 月发布)。将编译器版本包含在 OpenZeppelin Contract 的稳定性保证中,将迫使库要么坚持使用旧的编译器,要么发布频繁的主要更新,仅仅是为了跟上较新的 Solidity 版本的步伐。

因此,最低要求的 Solidity 编译器版本不是稳定性保证的一部分,并且用户可能需要在使用较新版本的 Contracts 时升级其编译器。bug 修复程序仍将向后移植到较旧的库版本,以便当前使用的所有版本都收到这些更新。

你可以在 此处 阅读有关此背后的基本原理、我们考虑的其他选项以及我们选择这条道路的原因的更多信息。

← 配合升级使用

访问控制 →

  • 原文链接: docs.openzeppelin.com/co...
  • 登链社区 AI 助手,为大家转译优秀英文文章,如有翻译不通的地方,还请包涵~
点赞 0
收藏 0
分享
本文参与登链社区写作激励计划 ,好文好收益,欢迎正在阅读的你也加入。

0 条评论

请先 登录 后评论
OpenZeppelin
OpenZeppelin
江湖只有他的大名,没有他的介绍。