How to build, test and document rgxr.
cargo matches what CI and the containers run (stable
toolchain).nix develop drops into the dev
shell with tern + pandoc for the docs, bun for the frontend, graphviz +
dot2tex + texlive for the render pipeline, jq/yq, openbao.migrations/ automatically at
startup via sqlx::migrate!.nix develop # dev shell (Rust itself: rustup, not Nix)
docker run -d --name rgxr-pg -p 5432:5432 \
-e POSTGRES_USER=rgxr -e POSTGRES_PASSWORD=rgxr -e POSTGRES_DB=rgxr \
postgres:17-alpine
DATABASE_URL=postgres://rgxr:rgxr@localhost:5432/rgxr \
RGXR_DEV_MODE=true cargo run -p rgxr-api
# api: http://localhost:8080/healthz
# api-docs (Swagger): http://localhost:8080/api-docs
cd web && bun install && bun run dev
# web: http://localhost:5173 — the dev proxy forwards /api to :8080RGXR_DEV_MODE=true serves requests without a token as
anonymous and allows the Vite origin for CORS.
The images build the same way CI does:
docker build -f api.Dockerfile .
docker build -f web.Dockerfile web/Exactly as CI runs them:
cargo fmt --check
cargo clippy --workspace --all-targets --locked
cargo test --workspace --lockedWorkspace clippy lints unwrap_used and
expect_used are deny (root
Cargo.toml, [workspace.lints.clippy]; every
crate inherits via [lints] workspace = true, and new crates
MUST too). Tests are exempt via
#![cfg_attr(test, allow(clippy::unwrap_used, clippy::expect_used))]
at the crate root; tests/ integration crates get the same
attribute (there, panicking IS the assertion mechanism). In library and
request paths, recover instead: return Result, map to
FaError, or return an error envelope. A panic in prod code
fails review no matter how unlikely the path.
User-facing documentation lives in docs/*.md (plus the
top-level README.md, which compiles too) and renders to the
committed docs-html/ site via tern + pandoc (both in the
dev shell):
nix develop -c tern --update # once, or after changing .tern/config.toml
nix develop -c tern # incremental rebuildCommit the regenerated docs-html/ together with the
source change. Never hand-edit docs-html/ (overwritten on
every run) or .tern/data/ (replaced by
--update). Mermaid diagrams in markdown work; the pipeline
ships a mermaid filter. Screenshots live in
resources/images/ and are referenced from the docs by forge
/media/branch/... URLs, so no image-copy step exists.
The per-section walkthroughs (regex, editor, OPS, grammar, machines)
are data, not code: tutorial content lives in
web/src/lib/tutorial/ as typed step lists with inline
English and Spanish content (the dojo’s lines.ts is the
precedent). The pattern itself (opt-in lightbulb, sensei dock,
spotlight, [ SHOW ME ]) is described in Design notes.
Forgejo Actions (.forgejo/workflows/ci.yaml), on pushes
to master, on v* tags and on pull
requests:
cargo fmt --check,
clippy --workspace --all-targets --locked,
test --workspace --locked, with a throwaway Postgres
service for the tests that need one.bun install --frozen-lockfile,
bun run check (svelte-check; also enforces that
es.ts covers every en.ts key) and
bun run build.rgxr-api
and rgxr-web images, pushes them to GHCR (mutable
master tag for the test lane, immutable vX.Y.Z
for releases) and notifies the Kargo receiver. Promotion lanes are
described in Operations.Docs rendering stays local (tern); CI does not build
docs-html/.
Conventional-ish, one line: type(scope): summary. Types
seen in the log are feat, fix,
docs; the scope names the area (core,
api, web, render) and is omitted
when a change spans the tree. Work lands through PRs, and the summary
cites the issues it closes:
feat(core): PDA, TM and answer grading (#44 #45) (#53)
fix(web): reliable sensei problem generation + verified TM library (#58)