Datum

Appearance

Adding A Datum Satellite Crate ​

Datum satellites are datum-* crates that build on datum-core without expanding the core public API. datum-net is the reference pattern.

Crate Shape ​

Create the crate under crates/datum-<area>/ and add it to the root workspace:

toml
[workspace]
resolver = "2"
members = ["crates/datum-core", "crates/datum-<area>"]

Use the published crate name datum-<area> and the Rust library name datum_<area> (Cargo derives that library name from the package name unless an explicit [lib] override is needed). Keep release metadata aligned with datum-core: version = "0.9.0", edition = "2024", rust-version = "1.88", license = "Apache-2.0", repository/homepage/documentation URLs, readme, keywords, and categories. Every satellite crate root must include:

rust
#![forbid(unsafe_code)]

The satellite depends on the core by workspace-relative path and matching published version:

toml
[dependencies]
datum-core = { path = "../datum-core", version = "0.9.0" }

Do not move existing datum-core APIs into a satellite as part of adding the crate. Satellite work is additive unless a separate migration plan provides source-compatible re-export shims.

Tests, Docs, And CI ​

The Rust CI gate runs with --workspace, so a new workspace member is automatically covered by formatting, clippy, tests, bench compilation, and rustdoc. Add at least:

  • a crate smoke test under crates/datum-<area>/tests/;
  • feature tests for every shipped surface, including success, failure, cancellation, and backpressure where the area exposes it;
  • a docs page under docs/guides/ or docs/reference/, wired into docs/.vitepress/config.mts;
  • any guide index link needed so the page is discoverable and the docs job catches dead links.

The docs build must pass:

sh
npm --prefix docs run docs:build

Benchmarks And Roadmap ​

Datum's benchmark-before-ported rule applies to satellites too. A satellite feature is not counted as ported until it has a Criterion benchmark scaffold, a recorded result, and a roadmap table entry. For a new area, add:

  • crates/datum-<area>/benches/<area>.rs with harness = false in that crate's manifest;
  • roadmap/benchmarks/<area>.md with the same columns used by the core benchmark tables, including Datum CPU us/op;
  • either an Akka/Pekko comparison or an explicit note explaining why a meaningful head-to-head is deferred and what harness would make it possible.

If a feature changes a hot path, capture before/after data before claiming the port is complete.

Publishing Order ​

Publish datum-core first. A satellite manifest may use datum-core = { path = "../datum-core", version = "0.9.0" } locally, but cargo publish for the satellite cannot fully verify until that matching datum-core version exists on crates.io. For a family release, dry-run datum-core independently and treat a datum-net dry-run blocked on the not-yet-published matching datum-core version as expected release ordering, not as a reason to bump MSRV or change the dependency.