Skip to content

Latest commit

 

History

History
297 lines (229 loc) · 11.6 KB

CONTRIBUTING.md

File metadata and controls

297 lines (229 loc) · 11.6 KB

Contributing to Gortex

Thank you for considering contributing to Gortex! This guide will help you get started.

Come say hello

Most day-to-day discussion happens on Discord:

discord.gg/39MFHu3J5d

If you're new, join and introduce yourself — what you work on, which languages or ecosystems you care about, and what brought you to Gortex. It's the fastest way to:

  • find out whether someone is already working on the thing you want to build,
  • sanity-check a design before you write the code,
  • get unstuck on a build, a tree-sitter grammar, or a failing test,
  • coordinate on larger changes that touch several subsystems.

Issues and pull requests are still the source of truth for anything that ships. Discord is where the coordination happens so PRs don't collide.

Please also read the Code of Conduct; it applies to Discord, issues, and pull requests alike. Security issues go through SECURITY.md, not a public issue.

Licensing of contributions

Gortex is released under the Apache License, Version 2.0. By submitting a contribution (a pull request, patch, or other work) you agree that it is licensed to the project under the same Apache 2.0 terms, as described in section 5 of the License. You retain copyright in your contribution; the project retains a perpetual, worldwide, royalty-free license to use, modify, and redistribute it as part of Gortex.

Contributors are listed in CONTRIBUTORS.md. Add yourself to that file in a dedicated PR, linking your previous contributions, if you'd like to be credited.

Getting Started

Prerequisites

  • Go 1.26+ (the toolchain version is pinned in go.mod; CI builds with it)
  • CGO enabled and a working C/C++ compiler — tree-sitter grammars are C. On Windows the mingw-w64 toolchain works; that's what CI uses.
  • Git

Building

git clone https://github.com/zzet/gortex.git
cd gortex
go build -o gortex ./cmd/gortex/

A cold build compiles several hundred vendored tree-sitter grammars, so expect minutes rather than seconds the first time. Later builds hit the Go build cache and are fast.

Add -trimpath (as AGENTS.md and the Makefile do) if you work in more than one worktree: it keeps the Go build cache shared between them, at the cost of module-relative paths in stack traces. CI builds untrimmed.

make build does the same thing but adds -tags llama for the in-process llama.cpp LLM provider. The plain go build above is the configuration CI checks and is the right default for most work. Other optional build tags:

Tag Enables
llama In-process llama.cpp provider (llm.provider: local)
embeddings_onnx ONNX Runtime embedding backend
embeddings_gomlx (+ XLA) GoMLX embedding backend
netgo,osusergo,static_link The fully static Linux release build

Running Tests

make test PKGS=./internal/<pkg>/...   # the packages you touched
make test                              # every package

CI runs the suite under -race on Linux. A few packages — internal/indexer, internal/mcp and internal/graph/store_sqlite in particular — are slow under -race, so if you hit the default 10-minute panic, raise the timeout rather than assuming a hang. CI leaves SQLite's transpiled C and its libc out of race instrumentation, which makes those packages several times faster; to match it locally, add -gcflags=modernc.org/sqlite/lib=-race=false -gcflags=modernc.org/libc/...=-race=false.

To run a package the way CI does, one worker process per CPU:

TEST_RACE=true go run ./scripts/ci-test --partition mcp+store

Linting

make lint      # golangci-lint run --timeout=5m

A green test run is not the full CI gate. CI pins golangci-lint to v2.14.0 and fails the build on any finding. Run it locally before opening a PR — config lives in .golangci.yaml.

make fmt       # gofmt -s -w .

Running Benchmarks

make bench

Or target a single package:

go test -bench=. -benchmem ./internal/parser/languages/
go test -bench=. -benchmem ./internal/query/
go test -bench=. -benchmem ./internal/graph/

What CI checks

Your PR has to get past all of these (.github/workflows/ci.yml):

  • affected complete packages on PRs, and the full test suite on main/manual runs, under -race with coverage on ubuntu-24.04 and without -race on macos-latest and windows-latest, as up to four jobs per OS (macOS still race-checks the indexer's watcher tests). A batch of tests or a package that fails while other tests share the runner is rerun once, whole and alone; if every test passes then, the job passes and flags the failure as flaky. A data race, a panic, a crash or a timeout is never rerun.
  • go build on each OS
  • a static Linux build (netgo,osusergo,static_link) verified to be self-contained and smoke-tested inside debian:11 and alpine:3
  • golangci-lint
  • builds with the ONNX and GoMLX embedding tags
  • benchmarks for the parser, query, and graph packages

See CI test selection for full-suite fallbacks, the ci:full PR label, and the CI_FULL_TESTS=true repository rollback switch. CI/dependency changes and Dependabot PRs always run the full suite.

Additional workflows cover security scanning, the install script, init smoke tests, and skill drift.

How to Contribute

Reporting Bugs

  • Open an issue with a clear description
  • Include the output of gortex version and go version
  • Provide a minimal reproduction if possible

Suggesting Features

  • Open an issue describing the feature and its use case
  • For language support requests, say whether an upstream tree-sitter grammar exists — see Adding a Language for the tiers

Submitting Code

  1. Fork the repository
  2. Create a feature branch (git checkout -b feature/my-feature)
  3. Write tests for your changes
  4. Ensure tests for the packages you touched pass (make test PKGS=./internal/<pkg>/...); CI runs the full suite
  5. Ensure the linter is clean (make lint)
  6. Commit with a clear message
  7. Open a pull request and fill in the template

Small, focused PRs get reviewed fastest. If a change is large or crosses subsystem boundaries, raise it on Discord or in an issue first — it's much cheaper to redirect a design than a finished branch.

Adding a Language

This is one of the most impactful contributions. Gortex indexes languages through three engine tiers, in order of decreasing extraction depth and increasing ease:

  1. Bespoke tree-sitter — a vendored grammar under internal/parser/tsitter/ plus a hand-tuned extractor in internal/parser/languages/ with per-language S-expression queries. Worth it when you need ORM, contract, dataflow, or scope-aware call resolution.
  2. Regex — pattern-matched line scanning for languages with no upstream grammar. Shared block helpers live in helpers_indent.go.
  3. Forest signature-only — if alexaandru/go-sitter-forest already ships a grammar, add the module and append one row to forestLanguages in forest_registrations.go. Cheapest path, broadest coverage, no deep extraction.

docs/languages.md documents each tier, the current language matrix, and the exact steps — read it before you start.

Hand-written extractors implement the parser.Extractor interface (internal/parser/extractor.go) and are registered in RegisterAll in register.go. Registration order matters: extractors registered before registerForestLanguages claim their extensions ahead of the generic forest grammars.

What to extract (in priority order):

  • Functions/methods with EdgeMemberOf to their class/type
  • Classes/types/interfaces
  • Interface method specs in Meta["methods"] (enables IMPLEMENTS inference)
  • Imports
  • Call sites
  • Variables/constants

Reference implementations:

  • golang.go — the most complete extractor
  • python.go — simple OOP language
  • rust.go — systems language with impl blocks
  • nim.go / abap.go — regex-tier templates
  • yaml.go — simple config extractor

Every extractor ships a _test.go with at least a happy-path and an empty-input case. Debug the AST first — tree-sitter node types vary between grammars.

Code Style

  • Follow standard Go conventions (gofmt -s, go vet, golangci-lint)
  • No unnecessary abstractions — three similar lines is better than a premature helper
  • Comments explain why, not what; match the density of the surrounding code
  • Tests should be self-contained with inline source snippets
  • Extractor test helpers (nodesOfKind, edgesOfKind) are shared across test files

Project Structure

cmd/gortex/          CLI entry point and subcommands
pkg/gortex/          Public API for embedding Gortex in another Go program
docs/                Reference documentation (see below)
internal/
  analysis/          Communities, processes, hotspots, architecture rollups
  contracts/         Contract definitions and checking
  daemon/            Long-running daemon: lifecycle, watchers, federation
  graph/             Core graph data structures (Node, Edge, Graph)
  indexer/           Directory walker, file watcher, incremental reindex
  llm/               LLM providers and the `ask` agent
  mcp/               MCP server and tool handlers
  parser/            Extractor interface, tree-sitter plumbing, registry
    languages/       Per-language extractors (one file each)
    forest/          Generic signature-only extractor over go-sitter-forest
    tsitter/         Vendored grammar wrappers for the bespoke tier
  persistence/       SQLite graph store and sidecars
  query/             Query engine (BFS traversal, SubGraph)
  resolver/          Cross-file reference resolution, IMPLEMENTS inference
  review/            PR review and diff analysis pipeline
  search/            FTS adapter, trigram, and semantic search
  server/            HTTP transports and the web dashboard

internal/ holds many more focused packages than the ones above; those are the load-bearing ones to know first.

Public API (pkg/gortex)

New(opts ...Option) (*Engine, error) opens a SQLite graph store, which can fail — construction returns an error rather than a bare *Engine. Pass WithStorePath to keep the store at a path of your choosing and reuse the index on the next run; without it the store lives in a temp directory.

Every Engine must be closed. Close checkpoints the write-ahead log, closes the database handle, and removes the temp directory when New created one — skipping it leaks a file handle and a background goroutine.

Where to Read Next

Doc Covers
docs/architecture.md How the pieces fit together
docs/languages.md Language matrix and adding a language
docs/mcp.md MCP server, tool presets, transports
docs/cli.md CLI verb reference
docs/llm.md LLM provider configuration
docs/features.md Capability tour
AGENTS.md Repo conventions for coding agents
CLAUDE.md Imports AGENTS.md and adds the Claude Code-only notes

Questions?

Ask on Discord, open an issue, or start a discussion. We're happy to help!