Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
210 lines (142 loc) · 6.06 KB

CONTRIBUTING.md

File metadata and controls

210 lines (142 loc) · 6.06 KB

Contributing to Kai

Thanks for your interest in contributing to Kai. This guide covers what we accept, how to set up a development environment, and how to submit changes.

Have questions? Join us on Slack.

Scope

Kai is fully open source under Apache 2.0. This repo contains the core engine and CLI. The server components live in the kai-server repo.

What we accept

  • Bug fixes
  • Performance improvements
  • Determinism improvements
  • Documentation improvements
  • Additional language support (parsers, symbol extraction, call graphs)
  • CI integration enhancements
  • Test coverage improvements
  • CLI UX improvements

Server and cloud contributions (authentication, multi-tenancy, hosting, RBAC, SSO, etc.) are welcome in the kai-server repo.

What we will not accept in this repo

  • Changes that introduce network dependencies into kai-core
  • Breaking changes without prior discussion in an issue
  • License changes

These boundaries protect the architectural separation between the core engine and server. See docs/architecture-boundary.md for details.

Pull Request Process

Review requirements

  • All PRs require at least one maintainer approval
  • PRs must pass CI before merging
  • PRs must include tests if behavior changes
  • PRs must preserve deterministic behavior
  • PRs must not introduce prohibited dependencies (no net/http or cloud SDKs in kai-core)

Before you start

  • Check existing issues to avoid duplicating work
  • For large changes, open an issue first to discuss the approach
  • Keep PRs focused — one logical change per PR

Response times

  • Initial review within 5 business days
  • Major design discussions may take longer
  • If your PR has been waiting, ping us on Slack or in the PR

Decision authority

Maintainers reserve the right to decline contributions that conflict with project direction, architectural boundaries, or correctness guarantees. We'll always explain why.

Determinism Requirements

Kai's core promise is deterministic, reproducible results. Any change that affects the following must include regression tests:

  • Graph construction or hashing
  • Snapshot content or ordering
  • CI plan output or test selection
  • ChangeSet computation

Run the regression suite before submitting:

cd kai-cli && CGO_ENABLED=1 go test ./cmd/kai/ \
  -run "TestGraph_|TestSelection_|TestFalseNeg_|TestShadow_|TestFlaky_|TestCLI_|TestPerf_" \
  -v -count=1

If your change produces different output for the same input, it must be discussed in an issue first.

Architectural Boundary Rules

The scripts/check-core-purity.sh script enforces these rules in CI:

  • No net/http imports in kai-core
  • No cloud SDK dependencies in kai-core
  • No cloud provider URLs in kai-core
  • No server-specific concepts (tenant, org_id, sso, billing) in kai-core

Run it locally before submitting:

./scripts/check-core-purity.sh

Development Setup

Prerequisites

  • Go 1.24+
  • GCC or Clang (for CGO — tree-sitter and SQLite)
  • Git

Build

# CLI
cd kai-cli
CGO_ENABLED=1 go build ./cmd/kai

# Core library
cd kai-core
CGO_ENABLED=1 go build ./...

Run Tests

# All tests
cd kai-cli && CGO_ENABLED=1 go test ./...
cd kai-core && CGO_ENABLED=1 go test ./...

# Benchmarks
./bench/run_repos.sh --mode both -n 3

Project Structure

kai-cli/           CLI binary (commands, CI plan, shadow mode)
kai-core/          Core engine (tree-sitter parsing, graph, snapshots)
bench/             Benchmark harness
docs/              Architecture, licensing, and reference docs
scripts/           Enforcement and utility scripts

Code Style

  • Follow standard Go conventions (gofmt, go vet)
  • No unnecessary abstractions — simpler is better
  • Tests go next to the code they test (*_test.go)
  • Don't add comments that restate the code

Commit messages

Write clear, concise commit messages:

Fix barrel import re-export handling in extractImports

export { x } from './y' was not producing IMPORTS edges because
extractImports only handled import_statement and call_expression.
Added export_statement case with parseReexportSource helper.
  • First line: imperative mood, under 72 characters
  • Body: explain why, not just what

Developer Certificate of Origin (DCO)

All contributions must be signed off under the Developer Certificate of Origin. This certifies that you have the right to submit the code and that it can be distributed under the Apache 2.0 license.

Add a Signed-off-by line to your commits:

git commit -s -m "Fix barrel import re-export handling"

This adds a line like:

Signed-off-by: Your Name <your.email@example.com>

You can configure Git to do this automatically:

git config --global format.signoff true

PRs without DCO sign-off will not be merged.

Copyright Headers

Source files should include an SPDX copyright header:

./scripts/check-copyright-headers.sh          # Check
./scripts/check-copyright-headers.sh --fix     # Auto-add missing headers

Submitting Changes

  1. Fork the repository
  2. Create a branch from main
  3. Make your changes with tests
  4. Run ./scripts/check-core-purity.sh
  5. Sign off your commits (git commit -s)
  6. Ensure CI passes: go test ./... in each module
  7. Open a PR against main

Security Reporting

Vulnerabilities should not be submitted as public issues. See SECURITY.md for responsible disclosure instructions.

Reporting Issues

Questions

Open a discussion or join Slack.