Maintenance and compatibility

fresh-cbm is maintained by the UBC FRESH Lab. This page records the review cadence, compatibility rules, and cache rebuild triggers.

Review cadence

Cadence

Review

Monthly

CI health, dependency and security updates, open issues and pull requests, broken docs links, release-asset availability, and cache verification.

Quarterly

libcbm and CBM-defaults versions, package fingerprints, storage growth, compatibility/deprecation status, and docs accuracy.

Annual

Full cache rebuild plan, retention/removal of obsolete releases, and maintainer ownership.

Event-driven

Rebuild when a manifest trigger changes; triage security or correctness reports immediately.

Owners

The UBC FRESH Lab maintainers own the package and release decisions. A change to the cache schema, a new public cache family, a PyPI publication, or a deprecation needs maintainer approval.

Compatibility

  • The package follows semantic versioning.

  • fresh-cbm-state-v1 is the current cache schema.

  • A schema change that is not backward compatible needs a new schema name and a migration note.

  • The client must keep reading legacy manifests that omit optional metadata until a documented deprecation date.

  • A removed field or command gets a deprecation note in the changelog and one release of overlap where practical.

  • Exact values are not silently redefined. If a source model changes, publish a new cache identity and release rather than overwriting an old one.

Cache rebuild triggers

Rebuild a cache when any of these change:

  • carbon package fingerprint;

  • CBM defaults hash;

  • libcbm version;

  • treatment transition table;

  • track/classifier/boundary inventory;

  • yield curves;

  • HWP or fertilization configuration;

  • years, account schema, dtype, or array layout;

  • chain family.

Changing consumer targets does not require a state-cache rebuild.

Cache lifecycle

  1. Build with fresh-cbm-build.

  2. Validate sampled states with fresh-cbm-validate.

  3. Package with fresh-cbm-package.

  4. Publish assets under a versioned release.

  5. Verify with fresh-cbm-verify.

  6. Record the release identity and known gaps.

  7. Retire only with a changelog note and maintainer approval.

Triage

  • Correctness or integrity reports: reproduce, verify the cache identity, and block further use of the affected release if needed.

  • Compatibility reports: record the failing client/cache pair and preserve a legacy read path.

  • Feature requests: add to the roadmap; do not silently expand the chain family.

  • Security reports: follow the repository security policy and avoid publishing details before a fix.

Release and data safety

  • Do not commit multi-GB cache arrays to ordinary git history.

  • Use release assets or LFS, with checksums.

  • Keep credentials, private data, and machine-specific paths out of manifests, docs, and release notes.

  • Verify the public release after any settings or storage change.