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.

2.3 KiB Raw Blame History