From 458e9a1533b7e75d7916f6dd5cc3c6802c4d1391 Mon Sep 17 00:00:00 2001 From: Justin Starry Date: Sat, 31 Oct 2020 09:45:18 +0800 Subject: [PATCH] Codify breaking change guidelines (#13066) * Codify breaking change guidelines * feedback * Rename title and add expectations section * Update docs/src/apps/backwards-compatibility.md Co-authored-by: Tyera Eulberg * Update docs/src/apps/backwards-compatibility.md Co-authored-by: Tyera Eulberg * Update docs/src/apps/backwards-compatibility.md Co-authored-by: Tyera Eulberg * Update docs/src/apps/backwards-compatibility.md Co-authored-by: Tyera Eulberg * Update docs/src/apps/backwards-compatibility.md Co-authored-by: Tyera Eulberg * Update docs/src/apps/backwards-compatibility.md Co-authored-by: Tyera Eulberg * Update docs/src/apps/backwards-compatibility.md Co-authored-by: Tyera Eulberg * Update backwards-compatibility.md * Update docs/src/apps/backwards-compatibility.md Co-authored-by: Trent Nelson * Update docs/src/apps/backwards-compatibility.md Co-authored-by: Trent Nelson * Update docs/src/apps/backwards-compatibility.md Co-authored-by: Trent Nelson * Apply suggestions from code review Co-authored-by: Tyera Eulberg Co-authored-by: Trent Nelson * Specify rust crates and add deprecation process * Promise semver for software releases Co-authored-by: Tyera Eulberg Co-authored-by: Trent Nelson --- docs/sidebars.js | 1 + docs/src/apps/backwards-compatibility.md | 141 +++++++++++++++++++++++ 2 files changed, 142 insertions(+) create mode 100644 docs/src/apps/backwards-compatibility.md diff --git a/docs/sidebars.js b/docs/sidebars.js index 2f6a922e5f..00634e5675 100644 --- a/docs/sidebars.js +++ b/docs/sidebars.js @@ -71,6 +71,7 @@ module.exports = { "apps/javascript-api", "apps/builtins", "apps/sysvars", + "apps/backwards-compatibility", ], "Integrating": ["integrations/exchange"], "Validating": [ diff --git a/docs/src/apps/backwards-compatibility.md b/docs/src/apps/backwards-compatibility.md new file mode 100644 index 0000000000..0a4c6817f0 --- /dev/null +++ b/docs/src/apps/backwards-compatibility.md @@ -0,0 +1,141 @@ +--- +title: Backward Compatibility Policy +--- + +As the Solana developer ecosystem grows, so does the need for clear expectations around +breaking API and behavior changes affecting applications and tooling built for Solana. +In a perfect world, Solana development could continue at a very fast pace without ever +causing issues for existing developers. However, some compromises will need to be made +and so this document attempts to clarify and codify the process for new releases. + +### Expectations + +- Solana software releases include APIs, SDKs, and CLI tooling (with a few [exceptions](#exceptions)). +- Solana software releases follow semantic versioning, more details below. +- Software for a `MINOR` version release will be compatible across all software on the + same `MAJOR` version. + +### Deprecation Process + +1. In any `PATCH` or `MINOR` release, a feature, API, endpoint, etc. could be marked as deprecated. +2. According to code upgrade difficulty, some features will be remain deprecated for a few release + cycles. +3. In a future `MAJOR` release, deprecated features will be removed in an incompatible way. + +### Release Cadence + +The Solana RPC API, Rust SDK, CLI tooling, and BPF Program SDK are all updated and shipped +along with each Solana software release and should always be compatible between `PATCH` +updates of a particular `MINOR` version release. + +#### Release Channels + +- `edge` software that contains cutting-edge features with no backward compatibility policy +- `beta` software that runs on the Solana Tour de SOL testnet cluster +- `stable` software that run on the Solana Mainnet Beta and Devnet clusters + +#### Major Releases (x.0.0) + +`MAJOR` version releases (e.g. 2.0.0) may contain breaking changes and removal of previously +deprecated features. Client SDKs and tooling will begin using new features and endpoints +that were enabled in the previous `MAJOR` version. + +#### Minor Releases (1.x.0) + +New features and proposal implementations are added to _new_ `MINOR` version +releases (e.g. 1.4.0) and are first run on Solana's Tour de SOL testnet cluster. While running +on the testnet, `MINOR` versions are considered to be in the `beta` release channel. After +those changes have been patched as needed and proven to be reliable, the `MINOR` version will +be upgraded to the `stable` release channel and deployed to the Mainnet Beta cluster. + +#### Patch Releases (1.0.x) + +Low risk features, non-breaking changes, and security and bug fixes are shipped as part +of `PATCH` version releases (e.g. 1.0.11). Patches may be applied to both `beta` and `stable` +release channels. + +### RPC API + +Patch releases: +- Bug fixes +- Security fixes +- Endpoint / feature deprecation + +Minor releases: +- New RPC endpoints and features + +Major releases: +- Removal of deprecated features + +### Rust Crates + +* [`solana-sdk`](https://docs.rs/solana-sdk/) - Rust SDK for creating transactions and parsing account state +* [`solana-program`](https://docs.rs/solana-program/) - Rust SDK for writing programs +* [`solana-client`](https://docs.rs/solana-client/) - Rust client for connecting to RPC API +* [`solana-cli-config`](https://docs.rs/solana-cli-config/) - Rust client for managing Solana CLI config files + +Patch releases: +- Bug fixes +- Security fixes +- Performance improvements + +Minor releases: +- New APIs + +Major releases +- Removal of deprecated APIs +- Backwards incompatible behavior changes + +### CLI Tools + +Patch releases: +- Bug and security fixes +- Performance improvements +- Subcommand / argument deprecation + +Minor releases: +- New subcommands + +Major releases: +- Switch to new RPC API endpoints / configuration introduced in the previous major version. +- Removal of deprecated features + +### Runtime Features + +New Solana runtime features are feature-switched and manually activated. Runtime features +include: the introduction of new native programs, sysvars, and syscalls; and changes to +their behavior. Feature activation is cluster agnostic, allowing confidence to be built on +Testnet before activation on Mainnet-beta. + +The release process is as follows: + +1. New runtime feature is included in a new release, deactivated by default +2. Once sufficient staked validators upgrade to the new release, the runtime feature switch + is activated manually with an instruction +3. The feature takes effect at the beginning of the next epoch + +### Infrastructure Changes + +#### Public API Nodes + +Solana provides publicly available RPC API nodes for all developers to use. The Solana team +will make their best effort to communicate any changes to the host, port, rate-limiting behavior, +availability, etc. However, we recommend that developers rely on their own validator nodes to +discourage dependence upon Solana operated nodes. + +#### Local cluster scripts and Docker images + +Breaking changes will be limited to `MAJOR` version updates. `MINOR` and `PATCH` updates should always +be backwards compatible. + +### Exceptions + +#### Web3 JavaScript SDK + +The Web3.JS SDK also follows semantic versioning specifications but is shipped separately from Solana +software releases. + +#### Attack Vectors + +If a new attack vector is discovered in existing code, the above processes may be +circumvented in order to rapidly deploy a fix, depending on the severity of the issue.