Skip to content

docs: refresh README — bump install version, document tracing feature, show Transaction::run example #120

@RAprogramm

Description

@RAprogramm

Problem

`README.md` has drifted from the current state of the crates:

  1. Installation snippet pins `entity-derive = "0.4"`. Latest is `0.8`. New users copy-pasting will start on a 4-major-version-old API.
  2. No mention of the `tracing` feature added in 0.8.0 (feat: opt-in tracing instrumentation on generated entity methods #118 / feat: opt-in tracing instrumentation on generated entity methods #119). Users have to dig into source to discover `features = ["tracing"]`.
  3. No transaction example showing the current `Transaction::new(&pool).run(async |ctx| { ... })` signature. The Features table says "Transactions: Multi-entity atomic operations" but doesn't show what calling them looks like — and the API just changed in 0.7.0 (fix: Transaction::run() never commits — closure signature change #103).
  4. No documented feature matrix for what each Cargo feature toggles (`postgres`, `clickhouse`, `mongodb`, `streams`, `api`, `validate`, `tracing`).

Fix

In `README.md`:

  • Bump the Installation block to use `version = "0.8"`.
  • Add a "Feature flags" section listing every Cargo feature with one-line descriptions.
  • Add a "Transactions" subsection under Quick Reference with a copy-pasteable `.run(async |ctx| { ... })` example that uses the current API.
  • Add a "Tracing" subsection showing how to enable the feature, what fields the spans carry, and a sample log line.

Out of scope

  • Wiki updates (separate repo, separate cadence).
  • Examples directory READMEs.

Acceptance

A new user reading the README top-to-bottom can:

  • copy the Installation snippet and get the latest crate;
  • find the list of optional features without grepping the codebase;
  • see how to use transactions correctly (with the fixed `run` signature);
  • enable structured logging in one feature flag.

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions