78 lines
3.4 KiB
Markdown
78 lines
3.4 KiB
Markdown
---
|
||
id: release-readme
|
||
name: Crate README (written last, honestly) + LICENSE + CHANGELOG
|
||
status: pending
|
||
depends_on: [release-crate-docs, release-deployment-matrix, release-contract-window-close, release-findings-2-3-disposition, release-n1-growth-posture]
|
||
scope: narrow
|
||
risk: low
|
||
impact: component
|
||
level: implementation
|
||
tags: [wave-8, docs, readme]
|
||
---
|
||
|
||
## Description
|
||
|
||
The plan's wave-8 "crate README (written last, honestly)" — the root
|
||
`README.md` does not exist yet, and it is written *last* so it
|
||
describes the shipped thing, not the intended one. Its dependencies
|
||
are the wave's other doc-shaped tasks for exactly that reason.
|
||
|
||
1. **`README.md`** (root, the crates.io-facing front page): what
|
||
alkstore is (one reactive store interface — notify, streams,
|
||
queues, locks, scheduler, outbox — over SQLite, Postgres, and the
|
||
in-process mem engine), the crate family table (which crate to
|
||
pick, per ADR-016's compile-time engine identity), the honest
|
||
posture lines per engine (single-host file-backed / multi-host /
|
||
honest-ephemeral, never fleet-valid), a minimal usage sketch
|
||
(compile-checked against the real API — the mem engine is the
|
||
zero-config example carrier), the contract-suite pointer (three
|
||
engines, one pinned contract), and the license note. No
|
||
aspirational claims: only what waves 1–7 shipped.
|
||
2. **LICENSE files**: `LICENSE-MIT` + `LICENSE-APACHE` at the root per
|
||
the family pattern (alkcall/alksocks ship both; the workspace
|
||
`license = "MIT OR Apache-2.0"` field is set but no license files
|
||
exist). The substrate's in-tree dual-license notice (ADR-018) stays
|
||
as landed — the root files do not replace it.
|
||
3. **`CHANGELOG.md`**: seeded per the family pattern — the 0.1.0
|
||
initial-release entry summarizing the contract v1 surface and the
|
||
three engines (honest, brief; the family's changelogs are
|
||
release-note-shaped, not commit logs).
|
||
4. **Per-crate readme wiring**: decide whether each published crate's
|
||
`[package] readme` points at the root README or gets its own short
|
||
crate-specific readme (the engines' lib docs already carry their
|
||
posture — a pointer-style per-crate readme is the likely honest
|
||
shape); land the decision.
|
||
5. **Honesty cross-check**: every README claim traceable to a spec
|
||
(core-contract.md, deployment.md, the engine specs) — this is the
|
||
"written last, honestly" discipline, and the review gate will
|
||
audit it.
|
||
|
||
## Acceptance Criteria
|
||
|
||
- [ ] Root `README.md` exists: family table, per-engine honest
|
||
postures, compile-checked usage sketch, suite pointer, license
|
||
note; no aspirational/unshipped claims
|
||
- [ ] `LICENSE-MIT` + `LICENSE-APACHE` at the root (MIT + Apache-2.0
|
||
canonical texts); ADR-018's in-tree substrate notice untouched
|
||
- [ ] `CHANGELOG.md` seeded with the 0.1.0 entry
|
||
- [ ] The per-crate readme wiring decided + landed
|
||
- [ ] Every README claim traceable to a spec (the trace list in Notes)
|
||
- [ ] Workspace gates green (docs-only expected)
|
||
|
||
## References
|
||
|
||
- docs/plans/implementation.md §Wave 8 (written last, honestly)
|
||
- docs/architecture/overview.md (the family/feature source)
|
||
- docs/architecture/deployment.md (the posture lines)
|
||
- docs/architecture/decisions/016-deployment-honesty.md,
|
||
docs/architecture/decisions/018-provenance-register-and-cherry-picks.md
|
||
- /workspace/@alkdev/alkcall/README.md + CHANGELOG.md (the family
|
||
pattern)
|
||
|
||
## Notes
|
||
|
||
> To be filled by implementation agent
|
||
|
||
## Summary
|
||
|
||
> To be filled on completion |