Skip to content

docs: align stability and support messaging with what the project actually does #397

Closed

Description

@adityamukho

Problem

The docs make promises that the current plan and history do not match:

  • PHILOSOPHY.md §7: "Once v1.0 ships, file format is stable for decades." Line 410: "Once v1.0 ships, format is frozen for decades." But v1.0 shipped on 2026-05-02, and v3.0.0 moves to format v8 and drops v1–v6 read support.
  • PHILOSOPHY.md line 365 has a check mark on "Known for never losing data". But bug: same-transaction multi-valued facts read back as ONE value, differing between EAVT and AEVT; a batched retract can leave retracted values visible #371 (silent loss of same-transaction multi-values) is present in every v2.x release.
  • PHILOSOPHY.md line 46: "12-15 months to production". ROADMAP.md line 3: "production-ready". These disagree with each other and with the open data-integrity issues.
  • .github/SECURITY.md lists only "latest 1.x minor line" as supported. The current line is 2.x.
  • The project released three major versions (v1, v2, v3 planned) within about 5 months, but no written policy says how long a major version gets fixes.

Ask

  • Rewrite the stability section as a policy, not a promise:
    • what counts as a format change;
    • how long each format version stays readable after it is superseded (for example: v(N+1) always reads v(N); drop v(N−1) only in the next major);
    • the migration guarantee.
  • Add a support policy: which major and minor lines get security and data-integrity fixes, and for how long after the next major ships. For example, "v2.x gets data-integrity fixes for 12 months after v3.0.0".
  • Fix the SECURITY.md version table.
  • Replace "production-ready" and "never losing data" with claims that are accurate today. Link to the tracker issue and the durability guide.
  • Update the wiki pages that repeat these claims (Comparison.md, Use-Cases.md).

Metadata

Metadata

Assignees

No one assigned

    Labels

    documentationImprovements or additions to documentationstabilityStability/panic issue

    Type

    No type

    Projects

    No projects

      Milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions