Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
83 lines (64 loc) · 2.81 KB

CONTRIBUTING.md

File metadata and controls

83 lines (64 loc) · 2.81 KB

Contributing to gnoma

The upstream repository lives at https://somegit.dev/Owlibou/gnoma and is mirrored to https://github.com/VikingOwl91/gnoma. PRs are accepted on the upstream (Gitea) instance; the GitHub mirror is read-only.

Setup

git clone https://somegit.dev/Owlibou/gnoma && cd gnoma
make build   # requires Go 1.26+
make test
make lint    # requires golangci-lint

Development workflow

  1. Branch from main.
  2. Write tests first (TDD). Table-driven where possible, t.TempDir() for filesystem tests, testing/synctest for concurrent ones.
  3. make check (fmt + vet + lint + test) must pass.
  4. Conventional commits: feat:, fix:, refactor:, test:, docs:, chore:. No co-signing or "Generated-by" trailers.

Code style

  • Go 1.26 idioms (new(expr), errors.AsType[E], sync.WaitGroup.Go).
  • Structured logging with log/slog.
  • json.RawMessage for tool schemas (zero-cost passthrough).
  • Functional options for complex configuration.
  • Short, lowercase package names — no underscores.
  • Discriminated unions via struct + type discriminant, not interfaces.
  • Pull-based stream iterators: Next() / Current() / Err() / Close().

Testing

Command What it runs
make test unit tests
make test-integration tests behind //go:build integration — requires real API keys
make cover coverage → coverage.html
make lint golangci-lint run ./...
make check fmt + vet + lint + test
go test -bench=. ./internal/router/ router benchmarks

Integration tests are skipped by default.

Architecture

Read docs/essentials/INDEX.md before changing architectural boundaries. Key packages:

Package Purpose
internal/engine Agentic loop (stream → tool → re-query)
internal/router Multi-armed bandit arm selection
internal/provider LLM provider adapters
internal/tool Tool interface + registry
internal/mcp MCP client (JSON-RPC over stdio)
internal/plugin Plugin manifest, loader, manager
internal/elf Sub-agent (elf) system
internal/security SafeProvider boundary, firewall, output scanner
internal/skill Skill registry and templating
internal/slm Small-language-model classifier + arm
internal/tui Bubble Tea v2 terminal UI

ADRs live in docs/essentials/decisions/.

Reporting issues

File issues on the upstream Gitea instance with:

  • A short reproduction (commands, prompts, configs that triggered the bug).
  • Expected vs. actual behavior.
  • gnoma --version output and OS / architecture.
  • Provider and model in use, if relevant.
  • --verbose log output if it sheds light.

License

By contributing you agree your work is licensed under the Apache License 2.0.