New Releases and API Stability

Before every release, we publish a feature-frozen release candidate. The purpose of the release candidate is to have a period where the community can review the new code before the actual release. If important problems are discovered, several more release candidates may be required. After a week of no more changes to the release candidate, the new version is published.

After several months or a year, a new major release may come out. These are not scheduled, but will be based on the need to release breaking changes such as a redesign of a core feature of the library (e.g. access control in 3.0). Since we value stability, we aim for these to happen infrequently (expect no less than six months between majors). However, we may be forced to release one when there are big changes to the Solidity language.

We follow SemVer, which means API breakage may occur between major releases (which don’t happen very often).

While the internal implementation of functions may change, their semantics and signature will remain the same. The domain of their arguments will not be less restrictive (e.g. if transferring a value of 0 is disallowed, it will remain disallowed), nor will general state restrictions be lifted (e.g. whenPaused modifiers).

If new functions are added to a contract, it will be in a backwards-compatible way: their usage won’t be mandatory, and they won’t extend functionality in ways that may foreseeably break an application (e.g. an internal method may be added to make it easier to retrieve information that was already available).

Some of our Solidity libraries use structs to handle internal data that should not be accessed directly (e.g. Counter). There’s an open issue in the Solidity repository requesting a language feature to prevent said access, but it looks like it won’t be implemented any time soon. Because of this, we will use leading underscores and mark said struct s to make it clear to the user that its contents and layout are not part of the API.

No events will be removed, and their arguments won’t be changed in any way. New events may be added in later versions, and existing events may be emitted under new, reasonable circumstances (e.g. from 2.1 on, ERC20 also emits Approval on transferFrom calls).

Some contracts implement EIPs that are still in Draft status, recognizable by a file name beginning with draft-, such as utils/cryptography/draft-EIP712.sol. Due to their nature as drafts, the details of these contracts may change and we cannot guarantee their stability. Minor releases of OpenZeppelin Contracts may contain breaking changes for the contracts labelled as Drafts, which will be duly announced in the changelog. The EIPs included are used by projects in production and this may make them less likely to change significantly.

While attempts will generally be made to lower the gas costs of working with OpenZeppelin Contracts, there are no guarantees regarding this. In particular, users should not assume gas costs will not increase when upgrading library versions.

The API stability guarantees may need to be broken in order to fix a bug, and we will do so. This decision won’t be made lightly however, and all options will be explored to make the change as non-disruptive as possible. When sufficient, contracts or functions which may result in unsafe behavior will be deprecated instead of removed (e.g. #1543 and #1550).

Starting on version 0.5.0, the Solidity team switched to a faster release cycle, with minor releases every few weeks (v0.5.0 was released on November 2018, and v0.5.5 on March 2019), and major, breaking-change releases every couple of months (with v0.6.0 released on December 2019 and v0.7.0 on July 2020). Including the compiler version in OpenZeppelin Contract’s stability guarantees would therefore force the library to either stick to old compilers, or release frequent major updates simply to keep up with newer Solidity releases.

Because of this, the minimum required Solidity compiler version is not part of the stability guarantees, and users may be required to upgrade their compiler when using newer versions of Contracts. Bug fixes will still be backported to past major releases so that all versions currently in use receive these updates.

You can read more about the rationale behind this, the other options we considered and why we went down this path here.