[Português](MIGRATION.pt-BR.md)
# Migration
## There is nothing to migrate yet
- `0.1.0` is the FIRST published version of this product
- `0.1.1` follows it and changes nothing a caller can observe
- Nothing you wrote against `0.1.0` needs changing to move to `0.1.1`
- This document exists to state what will be stable from here on
- READ IT BEFORE YOU DEPEND ON ANYTHING THIS PRODUCT EMITS
## Versioning policy
- The version is stated as `version` in `Cargo.toml`
- The version has three parts, and each part answers a different question
- A patch release fixes behaviour without changing the contract
- A minor release adds to the contract without removing from it
- A major release may remove from the contract
- WHILE THE MAJOR PART IS `0`, THE MINOR PART CARRIES BREAKING CHANGE
### What counts as a breaking change
- Removing a command or renaming one
- Removing a global flag or changing what an existing flag means
- Removing a configuration key or changing the domain of an existing key
- Changing what an exit number means
- Removing a field from the envelope or changing the type of a field
- Changing the shape of `data` for an existing command
- Raising the minimum supported Rust version
### What does not count as a breaking change
- Adding a new command
- Adding a new global flag with a default that preserves current behaviour
- Adding a new configuration key with a default that preserves current behaviour
- Adding a field to the envelope
- Correcting a diagnostic message on the auxiliary channel
- Changing an internal implementation with no observable difference
## The minimum supported Rust version
- The minimum supported Rust version is `1.88`
- It is declared as `rust-version` in `Cargo.toml`
- So cargo refuses an older toolchain by name rather than failing later
- RAISING IT IS A BREAKING CHANGE
- IT IS NEVER DONE IN A PATCH RELEASE
- A toolchain is infrastructure, and infrastructure changes on somebody else's schedule
- A patch release should be safe to take without planning
- One that demands a new toolchain is not safe to take without planning
## What a consumer may treat as stable
- Three things are the contract you may build on
- The FIRST is the envelope and the names of its fields
- The SECOND is the exit numbers and what each one means
- The THIRD is the command names and the flag names
- TREAT THESE THREE AS THE INTERFACE, AND NOTHING ELSE
### The envelope
- `command` names the command that produced the answer
- `schema_version` names the version of the envelope shape
- `target_resolved` names the destination reached, when one was reached
- `target_source` names how that destination was chosen
- `data` carries the command's own result
- `gaps` carries what was asked for and not delivered, with the cause
- `applied` carries what the output pipeline did
- `checksum` carries the signature of the result, when it was asked for
- READ FIELDS BY NAME, NEVER BY POSITION
- An absent field is omitted rather than emitted as null
### The exit numbers
- The numbers are `0`, `2`, `3`, `4`, `5`, `6` and `7`
- They continue with `8`, `9`, `10`, `11`, `124`, `130` and `141`
- Each class of failure ends in a number of its own
- The meaning of each is published in Annex D of the requirements document
- A number that already means something will not be reassigned
### The command names
- Run `mariadb-cli meta commands` for the command tree in structured form
- Run `mariadb-cli meta schema` for the output contract of each command
- BUILD AGAINST `meta commands` RATHER THAN AGAINST A DOCUMENT
- The command tree is data, so it never drifts from what the binary does
## How `schema_version` signals a change
- `schema_version` sits inside every envelope, at the top level
- Its current value is `1`
- The number changes when the envelope shape changes in a way that breaks a reader
- So a reader can check one field and know whether its assumptions still hold
- CHECK `schema_version` BEFORE TRUSTING THE FIELDS AROUND IT
- REFUSE A VERSION YOU WERE NOT WRITTEN AGAINST
- Adding a field does not change the number, because adding breaks no reader
- Removing a field or changing a type does change it
- Run `mariadb-cli meta schema` to read the contract the running binary publishes
- Run `mariadb-cli meta version` for `envelope_schema_version`, which lives there
- It is NOT in the answer of `meta schema`, so read the version from `meta version`
## Where the contract lives
- The full contract is working material and is not published with the crate
- Annex A publishes the observable command surface
- Annex B publishes the global flags
- Annex C publishes the persisted configuration keys
- Annex D publishes the exit numbers
- The document is the specification, not a summary of the code
- Two proofs read it and refuse to pass unless every requirement is cited
- The document travels inside the published archive, so a consumer can read it