feat: render Markdown, mathematics and Mermaid diagrams server-side

2026-09-27 19:15:50 +02:00
commit 35bc42623b
72 changed files with 8914 additions and 0 deletions
@@ -0,0 +1,76 @@
+# Development
+
+How to work on scriptorium.
+
+## Prerequisites
+
+- Go 1.27.1, the newest stable release.
+- [just](https://github.com/casey/just) for the recipes.
+- gcc, because the race detector in `just gates` needs cgo.
+
+## Setup
+
+```sh
+git clone https://sourcedock.dev/petrbalvin/scriptorium.git
+cd scriptorium
+just build
+```
+
+## Recipes
+
+Every recipe in the project's file, and what it does. Taken from the file itself, so
+the names and the list match it exactly. A library produces no binary, so the
+recipes that carry one do not exist here.
+
+| Recipe | What it does |
+|---|---|
+| `just gates` | the definition of done: compile, format check, vet, modernisation, the test suite with the coverage floor, and the race detector |
+| `just build` | compiles every package, zero warnings |
+| `just test` | the full suite as CI runs it, with the coverage floor |
+| `just unit . 'TestName'` | a fast scoped run for iterating |
+| `just fuzz <target> <package>` | a time-boxed fuzz of one target, never a gate |
+| `just bench` | benchmarks, on an idle machine only |
+| `just fmt` | gofmt, in place |
+| `just fmt-check` | gofmt, zero diff |
+| `just vet` | `go vet` and `go fix -diff` |
+| `just clean` | removes the coverage profile |
+
+## Running a single test
+
+```sh
+go test -run TestName ./...
+```
+
+Add `-v` for the sub-test names, and `-race` when the change touches concurrency.
+`-count=1` defeats the test cache when a result looks stale.
+
+## Coverage
+
+```sh
+just test
+go tool cover -func=coverage.out
+```
+
+The `total:` line is the number that matters, and it stays at 80 percent or more.
+
+## Benchmarks
+
+```sh
+go test -run='^$' -bench=. -benchmem -count=5 ./...
+```
+
+Benchmark on an idle machine, and compare only runs made in one process against each
+other: runs in separate processes, or on a loaded machine, differ by more than the
+effects being measured.
+
+## Continuous integration
+
+Workflows live in `.gitea/workflows/` and run on the project's own runners. They are
+written by hand rather than through `just`, but they enforce the same set of gates, so
+a green `just gates` locally is the fastest way to a green pipeline.
+
+## Releases
+
+Releases are cut by merging `development` into `main` and tagging `vX.Y.Z`. The tag
+drives the release workflow, which publishes the notes it extracted from
+`CHANGELOG.md`.