Contributing to GAIA

GAIA is an open source project, and we welcome contributions of all kinds. This guide will help you get started with contributing.

Ways to Contribute

Code

Bug fixes, new features, performance improvements, and refactoring

Documentation

Improve guides, add examples, fix typos, and translate content

Testing

Write tests, improve coverage, and report bugs

Design

UI/UX improvements, design assets, and accessibility enhancements

Getting Started

Read the Code of Conduct

Review our Code of Conduct to understand our community standards.

Set Up Development Environment

Follow the Development Setup Guide to configure your local environment.

Find an Issue

Browse GitHub Issues for tasks labeled good first issue or help wanted.

Fork and Clone

Fork the repository and clone it to your machine.

Contribution Workflow

1. Create a Branch

Create a feature branch from master:

git checkout -b feat/my-new-feature

Use conventional branch naming:

feat/ - New features
fix/ - Bug fixes
docs/ - Documentation changes
refactor/ - Code refactoring
test/ - Adding tests
chore/ - Maintenance tasks

2. Make Changes

Write your code following our Code Style Guidelines:

# Make your changes
vim apps/api/app/agents/tools/my_tool.py

# Test locally
cd apps/api
uv run pytest tests/test_my_tool.py

# Lint and format
nx lint api
nx format api

3. Commit Your Changes

Follow Conventional Commits format:

git add .
git commit -m "feat(agents): add weather forecast tool

- Add 5-day forecast support
- Include precipitation probability
- Add temperature range display

Closes #123"

4. Push and Create PR

Push your branch and create a pull request:

git push origin feat/my-new-feature

Then open a PR on GitHub following our PR Guidelines.

Development Guidelines

Testing Requirements

All PRs must include tests for new functionality.

# Run all tests
nx run-many -t test

# Run specific project tests
cd apps/api && uv run pytest

# Check coverage
uv run pytest --cov=app --cov-report=html

Code Quality

Ensure code passes all checks:

# Lint
nx run-many -t lint

# Format
nx run-many -t format

# Type check
nx run-many -t type-check

# Build
nx run-many -t build

Pre-commit Hooks

Install pre-commit hooks to catch issues early:

# Install hooks
pre-commit install

# Run manually
pre-commit run --all-files

Configured hooks (.pre-commit-config.yaml):

Check YAML, JSON, TOML syntax
Detect merge conflicts
Check for large files
Validate Python AST
Detect private keys and secrets

Coding Standards

Python (Backend)

Python Standards

Linting: Ruff (configured in pyproject.toml)
Formatting: Ruff format
Type Checking: mypy with strict mode
Style: PEP 8
Imports: At top of file, no inline imports
Type Hints: Required for all function parameters and return values
Docstrings: Google style for classes and public functions

# Good
async def create_todo(
    user_id: str,
    title: str,
    due_date: Optional[datetime] = None,
) -> dict[str, Any]:
    """Create a new todo item.

    Args:
        user_id: The user's unique identifier
        title: Todo title
        due_date: Optional due date

    Returns:
        Dictionary with todo data and success status
    """
    pass

# Bad
def create_todo(user_id, title, due_date=None):  # No types
    pass

TypeScript/JavaScript (Frontend)

TypeScript Standards

Linting: Biome (configured in biome.json)
Formatting: Biome format
Line Width: 80 characters
Indentation: 2 spaces
Imports: At top of file, no inline imports
Type Safety: Never use any type
File Organization: Feature-based structure

// Good
interface TodoItem {
  id: string;
  title: string;
  completed: boolean;
  dueDate?: Date;
}

async function createTodo(
  title: string,
  dueDate?: Date,
): Promise<TodoItem> {
  // Implementation
}

// Bad
async function createTodo(title: any, dueDate: any): any {  // Never use 'any'
  // Implementation
}

General Principles

No unnecessarily verbose comments - Code should be self-documenting
Feature-based organization - Group related files by feature, not type
Absolute imports - Use path aliases (@/ for frontend)
Single responsibility - Keep functions and components focused
Error handling - Always handle errors gracefully

Documentation

Update documentation for:

New features and APIs
Configuration changes
Breaking changes
Migration guides

# Preview docs locally
nx dev docs

Pull Request Checklist

Before submitting:

Code follows style guidelines
Tests pass locally
New tests added for new functionality
Documentation updated
Commit messages follow conventional format
PR title follows conventional format
No merge conflicts with master
Changes are focused and atomic

Review Process

Automated Checks

CI runs tests, linting, and type checking automatically.

Code Review

Maintainers review your code and provide feedback.

Address Feedback

Make requested changes and push updates.

Approval and Merge

Once approved, maintainers will merge your PR.

Review Expectations

Response time: We aim to review PRs within 2-3 business days
Feedback: Constructive and specific
Iteration: Multiple rounds may be needed
Communication: Ask questions if feedback is unclear

Commit Message Guidelines

Follow Conventional Commits format.

Examples

# Feature
feat(agents): add weather forecast tool

# Bug fix
fix(api): resolve todo creation race condition

# Documentation
docs: update agent development guide

# Refactoring
refactor(tools): simplify tool registry logic

# Performance
perf(api): optimize database queries

# Breaking change
feat(api)!: change authentication flow

BREAKING CHANGE: Auth tokens now expire after 1 hour

PR Description Template

Use this template for pull requests:

## Description
Brief description of changes

## Type of Change
- [ ] Bug fix
- [ ] New feature
- [ ] Breaking change
- [ ] Documentation update

## Changes Made
- Change 1
- Change 2
- Change 3

## Testing
How to test these changes

## Screenshots (if applicable)
![Description](url)

## Checklist
- [ ] Tests pass
- [ ] Documentation updated
- [ ] No breaking changes (or documented)

## Related Issues
Closes #123
References #456

Getting Help

Discord Community

Ask questions and get real-time help

GitHub Discussions

Start conversations about features and ideas

Documentation

Browse comprehensive guides and references

GitHub Issues

Report bugs and request features

Recognition

Contributors are recognized in:

README contributors section
Release notes
Community spotlights

Thank you for contributing to GAIA!

Next Steps

Code Style

Detailed code style guidelines

Pull Requests

PR process and requirements

Conventional Commits

Commit message format

Getting Started

Frontend Development

Backend Development

Agent Development

Contributing

​Ways to Contribute

Code

Documentation

Testing

Design

​Getting Started

​Contribution Workflow

​1. Create a Branch

​2. Make Changes

​3. Commit Your Changes

​4. Push and Create PR

​Development Guidelines

​Testing Requirements

​Code Quality

​Pre-commit Hooks

​Coding Standards

​Python (Backend)

​TypeScript/JavaScript (Frontend)

​General Principles

​Documentation

​Pull Request Checklist

​Review Process

​Review Expectations

​Commit Message Guidelines

​Examples

​PR Description Template

​Getting Help

Discord Community

GitHub Discussions

Documentation

GitHub Issues

​Recognition

​Next Steps

Code Style

Pull Requests

Conventional Commits

Build docs developers (and LLMs) love

Ways to Contribute

Getting Started

Contribution Workflow

1. Create a Branch

2. Make Changes

3. Commit Your Changes

4. Push and Create PR

Development Guidelines

Testing Requirements

Code Quality

Pre-commit Hooks

Coding Standards

Python (Backend)

TypeScript/JavaScript (Frontend)

General Principles

Documentation

Pull Request Checklist

Review Process

Review Expectations

Commit Message Guidelines

Examples

PR Description Template

Getting Help

Recognition

Next Steps