oli/rdbms-playground
1
0
Fork 0
Code Issues 4 Pull Requests Actions Packages Projects Releases 1 Wiki Activity

docs: move website ADR + plan into a dedicated docs/website/ namespace

Browse Source 
The website subproject drew ADR numbers from the same global integer pool
as main, so every merge risked a collision — this already happened twice
(drafted 0042, bumped to 0044, both landing on numbers main had taken; main
has now used 0044 for relationship visualization). Give the website its own
ADR namespace so the two never compete again.

- docs/adr/0044-public-website-...md
    -> docs/website/adr/20260604-adr-website-001.md  (id: ADR-website-001)
- docs/plans/20260604-adr-0044-website.md
    -> docs/website/plans/20260604-website-implementation-plan.md
- new docs/website/adr/README.md index (dated <date>-adr-website-<NNN> seq)
- docs/adr/README.md: drop the 0044 entry, add a namespace pointer in the
  intro (keeps the list tail == merge-base, so main's 0044 merges cleanly)
- ADR-0000: record the subproject-ADR-namespace convention
- update references in STYLE.md, astro.config.mjs, the plan body

Handoff files left untouched as point-in-time history.
This commit is contained in:
claude@clouddev1
2026-06-10 11:04:55 +00:00
parent 39e97ac3f9
commit dfb5f0b1b1
7 changed files with 62 additions and 15 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/website/adr/20260604-adr-website-001.md
+133
View File
@@ -0,0 +1,133 @@
# ADR-website-001: Public website and documentation site
## Status
Accepted (2026-06-04). Implementation plan:
[`docs/website/plans/20260604-website-implementation-plan.md`](../plans/20260604-website-implementation-plan.md).
> History: drafted as ADR-0042, renamed to ADR-0044 (each collided with a
> number `main` had independently assigned — H1a took 0042, compound-PK FK
> took 0043, then relationship-visualization took 0044). Moved to the
> website ADR namespace (`docs/website/adr/`, id **ADR-website-001**) on
> 2026-06-10 to end the recurring cross-branch number collision: website
> decision records now draw from their own dated sequence and never the
> main global ADR pool (see ADR-0000 "Numbering discipline"). Content is
> unchanged from the original draft.
## Context
RDBMS Playground is nearing its first public release and needs a public
website that does two jobs: **attract** — a landing page that shows the
playground in action — and **document** — a thorough, canonical reference
for everything the playground can do.
The documentation-heavy surface is already implemented and verified (full
simple- and advanced-mode command set, the ten-type vocabulary,
relationships, constraints, indexes, EXPLAIN, undo/history/replay, projects,
export/import, the teaching echo, clipboard, friendly errors, tab completion
and syntax highlighting; 2151 tests passing at the time of writing). The
site is therefore largely a presentation-and-writing effort, not a
wait-for-features one. A grounded inventory of what is shippable now lives
in the implementation plan.
Several choices here had no canonical default; they were settled during a
planning + `/runda` pass with the user and are recorded below.
## Decision
1. **Stack — Astro 6 + Starlight + Tailwind v4.** Astro's content-first,
zero-JS-by-default model with the Starlight docs theme fits a
marketing-landing-plus-heavy-docs site better than the alternative
considered, SvelteKit + Tailwind (the usual go-to here). Interactive
pieces are added as Astro islands (Svelte or vanilla), so Svelte is still
available where it earns its place. Tailwind v4 is wired via the official
`@tailwindcss/vite` plugin; the `@astrojs/starlight-tailwind` plugin
bridges Tailwind with Starlight's theming.
2. **Demo medium — asciinema.** Showcase sequences are recorded as
asciinema `.cast` files (text-based, small, faithful to the full
alternate-screen render) and embedded with `asciinema-player`. The same
casts are reused inline in the docs — one recording format serves both
the landing page and documentation enrichment. Recordings are produced by
a **scripted-input driver** that types commands into a real PTY with
viewer-friendly pacing; the app's own `history.log` **replay** (ADR-0034)
re-executes commands without typing animation or pacing and is therefore
suitable only for state-deterministic docs snippets, not the hero demo.
3. **In-page WASM playground — deferred** (OOS: **deferred**, not rejected).
A live, type-it-yourself playground compiled from the Rust app to
WebAssembly is desirable but is a multi-week sub-project, so it does not
block the site. The demo section is designed with a stable seam (a single
`Demo` component contract) so a WASM playground island can replace the
asciinema player later with no change to call sites. Recorded boundary
for that future work:
- **Portable core (runs on `wasm32-unknown-unknown` largely as-is):**
`src/dsl/*` (parser, types, grammar, walker), the pure `App::update()`,
`ui.rs`, `theme.rs`, `friendly/*`, output rendering; an in-memory DB
path already exists (`Connection::open_in_memory()`). `rusqlite`
compiles to the browser target via its `ffi-sqlite-wasm-rs` feature.
- **Native edge needing `cfg`-gated browser replacements:** the
multi-thread Tokio runtime + the dedicated DB **worker thread**
(ADR-0010) → current-thread/in-line async; `crossterm` terminal +
event-stream → a browser backend (e.g. Ratzilla's DOM/Canvas) + DOM
events; `arboard`, `zip`, file persistence (ADR-0015), file logging;
and the rusqlite **backup-API** undo (ADR-0006) → a SQL dump/restore.
When taken up, this becomes its own ADR + iteration plan.
4. **Hosting — portable static build; Vercel is the likely target.** Astro 6
builds to static HTML/CSS with no adapter, so the output deploys equally
to Vercel, Cloudflare Pages, Netlify, or GitHub Pages. We avoid coupling
to any one host. **No CI yet** — the site is tested locally (`pnpm dev` /
`pnpm build`) until the repo reaches its public home.
5. **Repo topology — monorepo.** The site lives under `website/` in the
playground repo; the crate stays at the repo root. The repo as a whole
moves to its public home later; site and crate travel together.
6. **Canonical docs home — the website.** User-facing documentation lives on
the site. In-repo `docs/` keeps ADRs, handoffs, and development notes;
`docs/simple-mode-limitations.md` (requirement DOC1) was a development aid
and now *feeds* the site's content rather than competing with it. The
sharing recipes promised by requirement E2 become a docs page.
7. **Documentation scope and conventions.** Document the **full supported
feature set**. Any capability not yet fully implemented (a small minority
— e.g. multi-line input, query cancellation, `seed`, `m:n` convenience,
ER-diagram export, the `show tables`/`relationships`/`indexes` family) is
either omitted or carries a clear **"planned / not yet available"**
callout — never presented as shipped. Two wording rules bind all
user-facing copy:
- **No engine name** (SQLite/STRICT/rusqlite/PRAGMA) — continues the
user-facing posture of ADR-0002; copy says "the database"/"the engine".
- **No "DSL"** — it is internal jargon. The two input modes are **simple
mode** (the playground's keyword command language) and **advanced
mode** (SQL).
8. **Install documentation — two mechanisms.** The install page documents
**prebuilt release binaries** (self-hosted download — not GitHub
Releases, since the repo will move) and **package managers**. Both can be
written now against the planned mechanisms; concrete download URLs slot in
at release. (Distribution items D1–D3 in `requirements.md` remain the
tracking home for the release tooling itself.)
## Consequences
- The site can ship on the strength of already-implemented features; it is
gated on writing and recording, not on finishing the app.
- One recording format (asciinema `.cast`) serves both marketing and docs,
and is reusable as the app evolves (re-run the script, re-record).
- The WASM playground is preserved as a real future option without holding
up launch; the demo seam keeps the upgrade cheap.
- A single canonical docs home removes the divergence risk of maintaining
user docs in two places.
- Website build choices (Decisions 1, 2, 4, 5) are recorded here for
traceability but do not, by themselves, warrant further ADRs; only
app-architecture decisions (notably the future WASM port) will.
## Out of scope
- **In-page WASM playground** — *deferred* (see Decision 3); revisit as its
own ADR + iteration plan.
- **Hosted/SaaS playground or a server-backed doc CMS** — *rejected*: a
static site fully satisfies the need, consistent with ADR-0007's
no-hosted-publishing stance. Revisit only if real demand emerges.
docs/website/adr/README.md
+19
View File
@@ -0,0 +1,19 @@
# Website Architecture Decision Records
Decision records for the **public website + documentation site** subproject
(the Astro/Starlight site under `website/`). These are kept in their own
namespace, separate from the project-wide ADRs in
[`docs/adr/`](../../adr/README.md), so website decisions never compete with
the main global ADR sequence for numbers — see
[ADR-0000 "Numbering discipline"](../../adr/0000-record-architecture-decisions.md).
**Numbering.** Files are named `<date>-adr-website-<NNN>.md` and referenced
in prose as `ADR-website-NNN`. The `<date>` (the ADR's accepted/created day,
`YYYYMMDD`) plus the `website` segment keeps the namespace disjoint from
`main`'s integers. Assign the next free `NNN` from this index. Every ADR
change updates this index in the same edit (the ADR-0000 index-upkeep rule
applies here too).
## Index
- [ADR-website-001 — Public website and documentation site](20260604-adr-website-001.md) — **Accepted 2026-06-04** (formerly ADR-0044 in the main index; moved here 2026-06-10 to end recurring cross-branch number collisions). The first public website: a marketing landing page plus the **canonical** user docs. Stack **Astro 6 + Starlight + Tailwind v4** (chosen over SvelteKit + Tailwind for a docs-heavy + marketing site; interactive bits as Astro islands). Showcase demos are **asciinema** `.cast` recordings (scripted-input driver for paced, re-recordable sessions — *not* `history.log` replay), reused inline in docs. The **in-page WASM playground is deferred** (OOS: deferred) behind a stable `Demo` seam, with the portable-core vs native-edge boundary recorded for a future ADR + iteration plan. Portable **static build** (Vercel target, but host-agnostic); **no CI yet**; **monorepo** (`website/`). Docs cover the **full supported feature set** with "planned" callouts for the unshipped minority; two wording rules bind user-facing copy — **no engine name** (continues ADR-0002) and **no "DSL"** ("simple mode" / "advanced mode"). Install docs cover **prebuilt binaries + package managers** (D1–D3 track the release tooling). Plan: [`docs/website/plans/20260604-website-implementation-plan.md`](../plans/20260604-website-implementation-plan.md)