Skip to main content

Contributing to GoatDB

Your contributions build the state layer that humans and AI agents share. Every feature you add, bug you fix, and optimization you make helps developers build realtime, offline-capable apps where people and agents work on the same live state.

:::tip[Ready to Start?] Check out our Good First Issues to find your first contribution opportunity. :::

What You're Building​

Simplicity for a Hard Problem: Your code eliminates the custom sync servers, conflict resolution, and state management that human-agent collaboration would otherwise require every app to build from scratch.

Distributed Systems Core: Work on Bloom filter synchronization, ephemeral CRDTs, and secure-mode cryptographically signed commit graphs that give agent actions a verifiable audit trail.

Cross-Runtime Support: Build features that work identically across Deno, Node.js, and browsers with a single TypeScript codebase.

Getting Started​

Prerequisites: Deno v2.4+ (install here) and Node.js v24+ for cross-runtime testing.

AI-Enhanced Development: GoatDB is optimized for AI-assisted development with Claude Code, Cursor, and ChunkHound.

Setup:

git clone https://github.com/goatplatform/goatdb.git
cd goatdb

# Verify cross-platform functionality
deno task test   # Tests across Deno, Node.js, and browsers
deno task bench  # Performance validation
deno task build  # Compile optimizations

# Documentation site
deno task docs:install  # Install docs dependencies (first time)
deno task docs:serve    # Docusaurus docs server

Testing & Performance​

Cross-Platform Testing: Ensure your changes work identically across all runtimes:

# All platforms
deno task test

# Specific environments
deno task test --runtime=browser
deno task test --runtime=node
deno task test --suite=DB --test="conflict resolution"

# Debug mode
deno task test --debug --deno-inspect-brk

Performance Validation: Maintain GoatDB's realtime performance characteristics:

# Full benchmark suite
deno task bench

# Specific scenarios
deno task bench --benchmark="GoatDB Sync Protocol"
deno task bench --runtime=browser --headless

Features: Single-process debugging, real-world metrics (P95, P99), source map support across all platforms.

:::tip[Quality Gate] Run deno task test && deno task bench before submitting to ensure no regressions. :::

Code Standards​

  • Formatting — deno fmt (2-space indent, single quotes, 80-char line width)
  • Naming — camelCase for variables/functions, PascalCase for classes, _prefix for private fields
  • Imports — explicit .ts extensions required
  • Cross-platform — code must work identically across Deno, Node.js, and browsers

Pull Request Checklist​

  • Descriptive title explaining your change's impact
  • All tests pass: deno task test across all platforms
  • Performance maintained: deno task bench shows no regressions
  • Documentation updated for API changes

Issues & Ideas​

Bug Reports: Include GoatDB version, target runtime, reproduction steps, and error messages.

Feature Requests: Check existing issues first, then use our feature request template.

Security: Email security issues privately to ofri [at] goatdb [dot] com.

Community​

License​

All contributions are licensed under the MIT license.

Ready to contribute? Your first pull request is just a fork away.