Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
136 lines (98 loc) · 4.04 KB

CONTRIBUTING.md

File metadata and controls

136 lines (98 loc) · 4.04 KB
Raw

Contributing to San

Thanks for your interest in contributing! This guide will help you get started.

Quick Start

git clone https://github.com/genai-io/san.git
cd san
git config core.hooksPath .githooks
go build -o san ./cmd/san
./san

Development

Git Hooks

The repo ships a pre-commit hook in .githooks/ that auto-formats staged Go files. The git config core.hooksPath .githooks step above activates it. Without it, CI will reject unformatted code.

The hook only formats files that have no unstaged changes, so partial stages (git add -p) are safe. Files with mixed staged/unstaged changes are skipped — format those manually with make format.

Prerequisites

  • Go 1.25+
  • An LLM API key (Anthropic, OpenAI, or Google)

Project Structure

cmd/               # Binary entrypoints (cmd/san)
docs/              # Documentation (architecture.md + packages/ + concepts/ + reference/ + guides/ + operations/)
internal/          # All Go code; see docs/reference/package-map.md for the full table
tools/             # Developer tooling (layercheck, …)
tests/integration/ # Cross-package behavioral tests
notes/             # Work-in-progress plans (not durable docs)

See docs/architecture.md for primitives and the runtime model. See docs/reference/package-map.md and docs/reference/dependency-rules.md for the full package list, layer assignment, and import rules. New package contributions also need a docs/packages/<name>.md following docs/packages/TEMPLATE.md.

Run Tests

GOCACHE=/private/tmp/san-go-build-cache go test ./...

Transcript/session focused suites:

GOCACHE=/private/tmp/san-go-build-cache go test \
  ./internal/session/... ./tests/integration/session/... ./tests/integration/cli/...

Before opening a PR, run make ci as the full local gate for CI-style checks. It runs the same Makefile checks as CI, including format checking (make format-check), build verification, linting, and coverage via make cover.

Transcript storage layout, recording rules, and the event model are documented in docs/packages/session.md.

Debug Mode

SAN_DEBUG=1 ./san
# Logs written to ~/.san/debug.log

How to Contribute

Report Bugs

Use the Bug report template. For security vulnerabilities, follow SECURITY.md instead — do not open a public issue.

Suggest Features

Use the Feature request template. For open-ended ideas, start a discussion first.

Submit Code

  1. Fork the repo
  2. Create a branch: git checkout -b feature/your-feature
  3. Make changes and test
  4. Commit with sign-off: git commit -s -m "feat: add feature"
  5. Push and open a PR

Commit Messages

Follow Conventional Commits:

feat: add new feature
fix: resolve bug
docs: update documentation
refactor: restructure code
test: add tests
chore: maintenance tasks

Areas for Contribution

Area Description
Providers Add new LLM providers (Ollama, Mistral, etc.); start with docs/guides/writing-a-provider.md
Tools Create new built-in tools
MCP Improve MCP server support
TUI Enhance terminal UI/UX
Docs Improve documentation
Tests Increase test coverage

Code of Conduct

This project follows the Contributor Covenant Code of Conduct. All participants are expected to uphold these standards.

Security

Found a security vulnerability? Please do not open a public issue. See our security policy for private reporting instructions.

Questions?

Start a discussion. We're happy to help!