nfs/docs/DEVELOPMENT.md

Development

How to work on nfs.

Prerequisites

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

Setup

git clone https://sourcedock.dev/petrbalvin/nfs.git
cd nfs
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.

Recipe	What it does
just gates	the definition of done: build, format check, vet, modernisation, the test suite with the coverage floor, and the race detector
just build	compiles cmd/nfsd and cmd/nfs into bin/nfsd and bin/nfs, zero errors and zero warnings
just test	the full suite with no test cache and the 80 percent coverage floor
just race	the same suite under the race detector
just unit ./internal/xdr 'TestName'	a fast scoped run for iterating
just fuzz FuzzXdr ./internal/xdr 60s	a time boxed fuzz of one target in one package
just bench	the benchmarks, five counts, allocation stats on
just fmt	gofmt over the tree, in place
just fmt-check	zero diff, prints nothing when everything is formatted
just vet	go vet and go fix -diff
just clean	removes bin/ and coverage.out
just install	builds, then copies bin/nfsd and bin/nfs into the user's bin directory
just uninstall	removes the installed binary
just run	runs the program in place; nfsd exits at once until it is given an export, so a real run passes flags to the built binary: ./bin/nfsd -export DIR
just dev	the same as run, for now

The test and bench recipes sweep ./internal/..., and not the whole tree: the thin cmd/nfsd and cmd/nfs count as zero coverage and would drag the floor below 80 percent on their own. The protocol logic lives under internal/.

Running a single test

go test -run TestName ./package

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

just bench

Benchmark on an idle machine, and compare only runs made in one process against each other.

Debugging the build

go build -gcflags='-m' ./...   # inlining decisions
go build -gcflags='-S' ./...   # what the compiler generated

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 builds the assets and publishes the notes it extracted from CHANGELOG.md.