M0030 contract-snapshot¶
Rule: A contract crate exports its version and keeps every version's schema snapshot in git, unchanged once in the base.
| Code | M0030 (stable, never reused) |
| Id | contract-snapshot |
| Category | workspace |
| Source | spirit_level |
| Fix | by hand |
| Needs | the crate map ([map] or map-file) |
Level per tier¶
| Tier | Level | Reason |
|---|---|---|
| small | off | |
| small-workspace | off | |
| medium | off | |
| big | deny |
every party of a contract knows its version and what that version looks like; a released snapshot never changes |
| ai | off | |
| embedded | off | |
| ui | off | |
| egui | off | |
| units-strict | off | |
| units-paranoid | off |
Parameters¶
| Name | Type | Default | Meaning |
|---|---|---|---|
const |
string | "VERSION" |
the integer constant of the library root that holds the contract's version |
snapshot |
string | "schema/v{version}.json" |
the snapshot of a version, in the crate's directory; {version} is the number |
base |
string | "main" |
the branch work merges into; a snapshot it has must not change |
Why¶
A contract crate holds the types that cross a process or node boundary, and every party links it. Parties are built and deployed at different times, so each must know which version of the contract it speaks and what that version looks like. The version constant answers the first; the schema snapshot of each version, kept in git, answers the second and lets a test check that a reader still reads what an older writer wrote. A snapshot that changes after it reached the base branch breaks that promise silently: a party built against it now reads something else under the same number.
The crates are the ones the crate map marks contract = true.
crates/foo_wire/
src/lib.rs pub const VERSION: u32 = 2;
schema/v1.json the schema of version 1, unchanged since it landed
schema/v2.json the schema of version 2
How to fix¶
- No version: add
pub const VERSION: u32 = 1;to the library root (parameterconstnames it). - No snapshot: write the schema of the current version to
schema/v<N>.json(parametersnapshot) and commit it. A test that generates the schema from the types and compares it with the file keeps it current. - Not in git: commit the snapshot.
- A snapshot changed against the base (parameter
base): restore it, bumpVERSION, and write the new schema to the next version's file. Readers tolerate unknown fields, so adding a field is a new version, not an edit.
Configure¶
[lints.contract-snapshot]
level = "deny"
const = "VERSION"
snapshot = "schema/v{version}.json"
base = "main"
reason = "why this project wants it at this level"
Allow one finding in the code with // spirit-level: allow(contract-snapshot) <reason> (waivers); the code works there too, as in [lints.M0030].