42 lines
1.8 KiB
Rust
42 lines
1.8 KiB
Rust
//! The version-stamp convention (ADR-017 §4.2, adopted here as the
|
|
//! suite's row discipline — ADR-022).
|
|
//!
|
|
//! Each property row is version-stamped with the contract change that
|
|
//! added it — ADR-017 §4.2's requirement that makes the suite
|
|
//! auditable against the core crate's changelog (whose entries cite
|
|
//! their ADRs by §2's no-silent-change rule).
|
|
//!
|
|
//! # The convention
|
|
//!
|
|
//! A row's stamp is a doc-comment list item beginning
|
|
//! **`Contract stamp:`** on the row's doc text, citing the ADR § (or
|
|
//! the backlog row) that pinned the behavior being tested:
|
|
//!
|
|
//! ```text
|
|
//! /// <one-line statement of the property>
|
|
//! ///
|
|
//! /// Contract stamp: ADR-008 §4 (reserved namespace, entry-point
|
|
//! /// validation); ADR-021 §3 (the schedule queue argument).
|
|
//! pub async fn row_name(factory: &dyn StoreFactory) { ... }
|
|
//! ```
|
|
//!
|
|
//! Rules:
|
|
//!
|
|
//! - The stamp cites the ADR § that pins the property — never a bare
|
|
//! "v1" or a date. A row may carry multiple stamps when it tests
|
|
//! several changes' behavior together (the exemplar row does).
|
|
//! - A row added to pin a new contract addition is stamped with that
|
|
//! addition's ADR; a row whose property predates the suite is
|
|
//! stamped with the ADR that pinned the behavior it tests.
|
|
//! - When a later contract change *amends* a row's property, the
|
|
//! row's stamp list gains the amending ADR (rows accumulate stamps;
|
|
//! the ADRs' own texts record the row history).
|
|
//! - `Contract stamp:` is greppable: `grep -r "Contract stamp:"
|
|
//! alkstore-contract-suite/` lists the suite's stamp inventory.
|
|
//!
|
|
//! Version 0 of the suite: this module *is* the convention's
|
|
//! normative statement; every later row cites its stamp against it.
|
|
|
|
/// The doc-comment marker introducing a row's version stamp.
|
|
pub const STAMP_MARKER: &str = "Contract stamp:";
|