scriptorium/docs/DEVELOPMENT.md

Development

How to work on scriptorium.

Prerequisites

• Go 1.27.1, the newest stable release.
• just for the recipes.
• gcc, because the race detector in just gates needs cgo.

Setup

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

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

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

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.