Vyper Versioning Guideline¶
Vyper has different groups that are considered “users”:
- Smart Contract Developers (Developers)
- Package Integrators (Integrators)
- Security Professionals (Auditors)
Each set of users must understand which changes to the compiler may require their attention, and how these changes may impact their use of the compiler. This guide defines what scope each compiler change may have, it’s potential impact based on the type of user, so that users can stay informed about the progress of Vyper.
|Group||How they use Vyper|
|Developers||Write smart contracts in Vyper|
|Integrators||Integerating Vyper package or CLI into tools|
|Auditors||Aware of Vyper features and security issues|
A big part of Vyper’s “public API” is the language grammar. The syntax of the language is the main touchpoint all parties have with Vyper, so it’s important to discuss changes to the language from the viewpoint of dependability. Users expect that all contracts written in an earlier version of Vyper will work seemlessly with later versions, or that they will be reasonably informed when this isn’t possible. The Vyper package itself and it’s CLI utilities also has a fairly well-defined public API, which consists of the available features in Vyper’s exported package, the top level modules under the package, and all CLI scripts.
This guide was adapted from semantic versioning.
It defines a format for version numbers that looks like
We will periodically release updates according to this format, with the release decided via
the following guidelines.
Changes to the grammar cannot be made in a backwards incompatible way without changing Major
It is to be expected that breaking changes to many features will occur when updating to a new Major release,
primarily for Developers that use Vyper to compile their contracts.
Major releases will have an audit performed prior to release (e.g.
x.0.0 releases) and all
severe vulnerabilities will be addressed that are reported in the audit report.
informational vulnerabilities should be addressed as well, although this may be
left up to the maintainers of Vyper to decide.
|Developers||Syntax deprecation, new features|
|Auditors||Audit report w/ resolved changes|
Minor version updates may add new features or fix a
and these will be detailed in the Release Notes for that release.
Minor releases may change the features or functionality offered by the package and CLI scripts in a
backwards-incompatible way that requires attention from an integrator.
Minor releases are required to fix a
informational vulnerability can be fixed in Patch releases,
alongside documentation updates.
|Developers||New features, security bug fixes|
|Integrators||Changes to external API|
Patch version releases will be released to fix documentation issues, usage bugs,
informational vulnerabilities found in Vyper.
Patch releases should only update error messages and documentation issues
relating to it’s external API.
|Developers||Doc updates, usage bug fixes, error messages|
|Integrators||Doc updates, usage bug fixes, error messages|
As Vyper develops, it is very likely that we will encounter inconsistencies in how certain language features can be used, and software bugs in the code the compiler generates. Some of them may be quite serious, and can render a user’s compiled contract vulnerable to exploitation for financial gain. As we become aware of these vunlerabilities, we will work according to our security policy to resolve these issues, and eventually will publish the details of all reported vulnerabilities here. Fixes for these issues will also be noted in the Release Notes.
There may be multiple Major versions in process of development.
Work on new features that break compatibility with the existing grammar can
be maintained on a separate branch called
next and represents the next
Major release of Vyper (provided in an unaudited state without Release Notes).
The work on the current branch will remain on the
master branch with periodic
new releases using the process as mentioned above.
Any other branches of work outside of what is being tracked via
will use the
-alpha.[release #] (Alpha) to denote WIP updates,
-beta.[release #] (Beta) to describe work that is eventually intended for release.
-rc.[release #] (Release Candidate) will only be used to denote candidate builds
prior to a Major release. An audit will be solicited for
and subsequent releases may incorporate feedback during the audit.
The last Release Candidate will become the next Major release,
and will be made available alongside the full audit report summarizing the findings.
Pull Requests can be opened against either
next branch, depending on their content.
Changes that would increment a Minor or Patch release should target
whereas changes to syntax (as detailed above) should be opened against
next branch will be periodically rebased against the
master branch to pull in changes made
that were added to the latest supported version of Vyper.
Major and Minor versions should be communicated on appropriate communications channels to end users, and Patch updates will usually not be discussed, unless there is a relevant reason to do so.