Skip to content

Contributing

Development setup

The tools you need to build, test and lint the repository, and how to run the checks.

Last updated:

You will learn#

  • which tools to install;
  • how to build and run the program from a clone;
  • the commands that check your change before you push.

The idea#

The repository is one Go module with a front end in web/ and the documentation site in site/. Task is the single entry point: the commands you run on your machine are the ones the pull request pipeline runs. Indentation is a tab of width 4 (.editorconfig), except in files whose format needs spaces, and Git expects LF line endings.

Quick start#

Install these tools:

ToolUsed for
Go, the version in go.modthe core, the engine, the service and the program
Taskthe commands below
golangci-linttask lint for Go
Bunweb/ (the project uses Bun there, not npm)
Node.js 24 and npmsite/ (the documentation site keeps npm)
FFmpeg 9the tests that encode; the container image carries a pinned one

Then, from the root of the clone:

Terminal
task setup
task ci

task setup checks the tools and activates the hooks of .githooks/: the pre-commit hook checks staged Go and Markdown files, and the pre-push hook refreshes the "Last updated" dates of the site. task ci runs task lint, task vet, task test, task tidy:check and task notices:check.

To run the program from the clone, build the front end with bun install and bun run build in web/ (the program embeds the files that the build writes), then go run ./web/cmd/app serve from the root. It behaves as the binary.

CommandDoes
task lintGo, Markdown, the web front end and the site
task testthe Go tests (go test -short)
task codegenregenerates the contracts, the TypeScript types and the FFmpeg pins
task site:buildbuilds the site and runs its checks
bun run check:thin-client (in web/)the rules of the thin client

Common mistakes#

  • Running npm install in web/, or bun in site/. Each folder has one package manager and one lockfile.
  • Skipping task codegen after changing a registry or schema: the Generated files check fails with a diff. Run it and commit the result.
  • Changing go.mod, web/package.json or a lockfile without task notices: task notices:check fails until the notices are regenerated.
  • Building the site with a Node.js version other than the one the pipeline uses (24): a different major can change the output of the build checks.

Next steps#