77 lines
2.3 KiB
Markdown
77 lines
2.3 KiB
Markdown
# 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`.
|