Development workflow

How to take a change from idea to merged PR.

1. Set up your environment

Follow getting started. Confirm you can build the project with the tooling for your OS (Apple Silicon: Go only; everywhere else: Go + CMake) and run the daemon with go run . serve.

2. File or pick up an issue

For non-trivial work, CONTRIBUTING.md asks for a discussion issue first. State the problem, why it matters, how you'd test it, and (bonus) draft documentation. This avoids spending effort on changes the maintainers won't accept (compatibility breaks, big new surface area).

3. Branch and code

Branch from main. Keep changes scoped to one logical area — most commits in the repo touch a single Go package. Match the existing patterns in that area (see patterns and conventions).

If you're adding a new model architecture:

• Conversion goes under convert/ (one convert_<arch>.go per family, mirroring convert_gemma.go etc.).
• Renderer/parser go under model/renderers/ and model/parsers/ if the model needs more than a Go template.
• Pure-Go inference (for ollamarunner) goes under model/models/<arch>/.
• Tokenizer additions live under tokenizer/.

If you're adding a new launch integration:

• Add cmd/launch/<name>.go mirroring an existing one (e.g., droid.go, opencode.go).
• Register it in cmd/launch/registry.go.
• Tests go in cmd/launch/<name>_test.go. Existing integrations have heavy table-driven golden tests; follow the same shape.

If you're adding a new HTTP route:

• Register it in Server.GenerateRoutes in server/routes.go.
• Wrap inference handlers with s.withInferenceRequestLogging(...) so they're captured by server/inference_request_log.go.
• For OpenAI/Anthropic compat, prefer adding middleware in middleware/ rather than branching inside the handler.

4. Test locally

go test ./...
go test -race ./...                            # detect data races
golangci-lint run                              # repo lint
go test -tags=integration ./integration/...    # integration suite

The unit suite runs in seconds for individual packages and a few minutes for the full module. Heavier suites — integration tests, GPU-dependent tests — are gated by build tags or by the presence of devices.

5. Open the PR

• Use the commit format from CONTRIBUTING.md: <package>: <short description>.
• Link the issue you opened in step 2.
• Keep the diff readable — large refactors should be split into focused commits.

6. Review and merge

CI runs .github/workflows/test.yaml and other checks defined in .github/workflows/. Address every comment; expect maintainers to push back on changes that grow public surface area or burden long-term maintenance (CONTRIBUTING.md is explicit about this).

Branch hygiene

The default branch is main. There is no separate dev branch in the repo's remote configuration. Releases are cut as tags like v0.22.1 (see git tag history); tagged binaries are published through .github/workflows/release.yaml.