# Versioning

From https://semver.org/#summary:

Given a version number MAJOR.MINOR.PATCH, increment the:

MAJOR version when you make incompatible API changes,
MINOR version when you add functionality in a backwards compatible manner, and
PATCH version when you make backwards compatible bug fixes.

---

## Crate updates
* new crate `casper-contract-abi-types`
* all types supported in `casper-contract` API (basically anything `CLTyped` except `CLType::Any`)
* `no_std` with no feature for `std`
* new crate `casper-bytesrepr`
* `no_std` with no feature for `std`
* new crate `casper-http-server-types`
* all types required by the three HTTP servers' APIs (event steam, REST, JSON-RPC)
* includes encoding and decoding to/from JSON
* no dependency on any other `casper-` crate; duplicates all types as required
* if we want to avoid serde derive on these types, need private types for each with one-to-one mapping
* we assume strict JSON encoding/decoding: adding, changing, renaming or deleting a field from a type requires a MAJOR version change
* creating a new type would constitute a MINOR version change
* refactor `casper-types`
* no support for `no_std`
* move remaining non-implementation detail types from EE here (most of EE/shared, error types, execution results, trie types)
* move remaining non-implementation detail types from node here (block, deploy, chainspec, timestamp)
* how to split into modules? (EE/stored value/node)
* could re-export three new crates above if we want this crate to be the one-stop shop for all required types of the reference implementation of Casper node, but then we have the `no_std` problem again
* if we want to keep these types separate from their implementations, we'd need to make all internal fields `pub` and would result in unusual API for them all where we couldn't call `self.method()`, but would need to do e.g. `method(&mut block)`, or else extensive use of traits to support `self.method()`

---

## Contract ABI version
* is a hard-coded unsigned integer value defined in `casper-contract`
* refers to the binary interface required for execution of a smart contract
* defined by the `casper-contract-abi-types` and bytesrepr impls of all these types
* bytesrepr impls on types not included above (e.g. blocks, p2p messages, tries) are NOT part of the Contract ABI

Examples
1. if we change `to_bytes` to be passed a mutable ref to an output buffer rather than returning a `Vec<u8>` - no ABI change
3. if we change `to_bytes` for integers to use big-endian rather than little-endian form - ABI change
2. if we add a new variant to the `Key` type - ABI change
4. if we add a new variant to the `StoredValue` type - no ABI change

## Contract API version
* is a hard-coded SemVer value defined in `casper-contract`
* refers to the interface defined in `casper-contract` for consumption by smart contracts
* if Contract ABI changes, API must have a MAJOR version change

## EE API version
* is a hard-coded SemVer value defined in `casper-execution-engine`
* refers to the full public API of the source code (should move many types)
* if Contract API changes, EE API must have at least the same degree of change (e.g. if Contract API has MINOR bump, EE API must have MINOR or MAJOR bump)

## Node ABI version
* concept encapsulating the notion of serialized data, including Contract ABI, all stored types (storage and global state) and wire format of P2P messages
* does not cover JSON-encoding
* is not specified as a value in the code
* no need for interoperation across different ABI versions for wire format, but there is for stored data

## Node API version
* is an unsigned integer value defined in `casper-node` (we don't support P2P comms between different versions, so every version bump is backwards incompatible)
* covers the P2P RPCs
* covers three HTTP servers, although they are versioned separately using SemVers
* if EE API changes, or any of the HTTP servers, Node API must increase

## Node HTTP server API versions
* is three hard-coded SemVer values, one per server, defined in `casper-node`
* covers the JSON-encoding of the types and the available endpoints/methods
* if casper-http-server-types version changes, relevant HTTP server APIs must have at least the same degree of change (e.g. if casper-http-server-types has MINOR bump on `Status` type, REST and JSON-RPC APIs must have MINOR or MAJOR bump)

## Protocol version
* is an unsigned integer value defined in chainspec
* defines the set of chainspec values which all validators must apply and the Node API version for that particular network
* should support a new chain being started at protocol version 1 with any Node API version
* after starting, must remain in lockstep with Node API version

## Client API version
* is a hard-coded SemVer value defined in `casper-client`
* client should support multiple versions of the JSON-RPC server

## Software version
* generally should be used to define API version, except for `casper-node`