ReviewOS

home-lang/home

Drop "88% complete" framing — replace with capability matrix + CHANGELOG

#8
Closed glennmichael123 opened this 24 days ago · 1 comment
24 days ago

Context

docs/ARCHITECTURE.md opens with:

Status: Home is at 88% completion (43/49 tasks complete)

No serious programming language is "88% complete" — languages evolve forever. This kind of framing in public docs hurts credibility with the audience we're trying to attract (systems / web devs evaluating Home seriously).

The same pattern shows up in the *-COMPLETE.md files (SESSION-STDLIB-COMPLETE.md, TESTING_COMPLETE.md, TOOLING_COMPLETE.md, BUN-FEATURES-IMPLEMENTED.md) — they read like internal milestone reports rather than user-facing documentation.

Proposal

  • Remove the "88% complete" line from ARCHITECTURE.md

  • Add a capability matrix to docs (or README) that's honest about what works and what doesn't:

    FeatureStatus
    Closures✅ Stable
    Pattern matching✅ Stable
    Trait objects🚧 In progress
    Const generics❌ Not yet
    arm64 codegen🚧 Partial
    wasm codegen🚧 Stub
    ……
  • Add a real CHANGELOG.md at repo root, going forward (Keep a Changelog format). Past changes can be reconstructed lazily from git log.

  • Demote the *-COMPLETE.md files into either internal-only notes (e.g. docs/internal/) or fold their useful content into the user-facing docs and delete the rest.

Why this matters

  • Honest "🚧 in progress" reads as confident; "88% complete" reads as overclaim
  • A capability matrix lets evaluators decide if Home is ready for their use case in 30 seconds
  • A CHANGELOG lets users decide whether to upgrade

Part of broader docs cleanup — the 43-file flat docs/ layout could use restructuring (see separate issue if filed).

24 days ago

Landed on main in 659d3be — capability matrix in README + docs/CAPABILITY_MATRIX.md, scaffolded CHANGELOG.md, demoted 10 *-COMPLETE.md files to docs/internal/.

Sign in to comment on this issue.