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 <teulberg@gmail.com> * Update docs/src/apps/backwards-compatibility.md Co-authored-by: Tyera Eulberg <teulberg@gmail.com> * Update docs/src/apps/backwards-compatibility.md Co-authored-by: Tyera Eulberg <teulberg@gmail.com> * Update docs/src/apps/backwards-compatibility.md Co-authored-by: Tyera Eulberg <teulberg@gmail.com> * Update docs/src/apps/backwards-compatibility.md Co-authored-by: Tyera Eulberg <teulberg@gmail.com> * Update docs/src/apps/backwards-compatibility.md Co-authored-by: Tyera Eulberg <teulberg@gmail.com> * Update docs/src/apps/backwards-compatibility.md Co-authored-by: Tyera Eulberg <teulberg@gmail.com> * Update backwards-compatibility.md * Update docs/src/apps/backwards-compatibility.md Co-authored-by: Trent Nelson <trent.a.b.nelson@gmail.com> * Update docs/src/apps/backwards-compatibility.md Co-authored-by: Trent Nelson <trent.a.b.nelson@gmail.com> * Update docs/src/apps/backwards-compatibility.md Co-authored-by: Trent Nelson <trent.a.b.nelson@gmail.com> * Apply suggestions from code review Co-authored-by: Tyera Eulberg <teulberg@gmail.com> Co-authored-by: Trent Nelson <trent.a.b.nelson@gmail.com> * Specify rust crates and add deprecation process * Promise semver for software releases Co-authored-by: Tyera Eulberg <teulberg@gmail.com> Co-authored-by: Trent Nelson <trent.a.b.nelson@gmail.com>
This commit is contained in:
parent
4b65e32f22
commit
458e9a1533
|
@ -71,6 +71,7 @@ module.exports = {
|
|||
"apps/javascript-api",
|
||||
"apps/builtins",
|
||||
"apps/sysvars",
|
||||
"apps/backwards-compatibility",
|
||||
],
|
||||
"Integrating": ["integrations/exchange"],
|
||||
"Validating": [
|
||||
|
|
|
@ -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.
|
Loading…
Reference in New Issue