​
Welcome Contributors! 🎉

Thank you for your interest in contributing to GAIA! We’re excited to have you join our community of developers building the future of personal AI assistants.

​
Getting Started

Before making your first contribution, please:

  1. Read our Code of Conduct
  2. Set up your development environment using our Development Setup Guide
  3. Explore the codebase to understand the architecture and patterns we use

​
Ways to Contribute

Bug Fixes

Help us squash bugs and improve stability

New Features

Add exciting new capabilities to GAIA

Documentation

Improve guides, add examples, or fix typos

Testing

Write tests to improve code coverage and reliability

​
Contribution Workflow

1

Fork & Clone

Fork the repository on GitHub and clone your fork locally:

git clone https://github.com/YOUR_USERNAME/gaia.git
cd gaia
git remote add upstream https://github.com/heygaia/gaia.git
2

Create a Branch

Create a new branch for your feature or fix:

git checkout -b feature/your-feature-name
# or
git checkout -b fix/bug-description
3

Make Changes

Make your changes following our coding standards and best practices.

4

Test Your Changes

Run the test suite to ensure your changes don’t break anything:

# Backend tests
cd backend && uv run pytest

# Frontend tests
cd frontend && pnpm test

# Linting
cd backend && uvx ruff check
cd frontend && pnpm lint
5

Commit & Push

Commit your changes with a descriptive message:

git add .
git commit -m "feat: add new AI capability for task management"
git push origin feature/your-feature-name
6

Create Pull Request

Open a pull request on GitHub with a clear description of your changes.

​
Coding Standards

​
Python Backend

​
Frontend (Next.js/React)

​
Commit Message Guidelines

We follow the Conventional Commits specification:

<type>[optional scope]: <description>

[optional body]

[optional footer(s)]

​
Types:

  • feat: A new feature
  • fix: A bug fix
  • docs: Documentation only changes
  • style: Changes that do not affect the meaning of the code
  • refactor: A code change that neither fixes a bug nor adds a feature
  • test: Adding missing tests or correcting existing tests
  • chore: Changes to the build process or auxiliary tools

​
Examples:

feat(ai): add new conversation memory system
fix(auth): resolve token expiration issue
docs(setup): update development environment guide
test(api): add unit tests for user service

​
Pull Request Guidelines

​
Before Submitting

  • Code follows our style guidelines
  • Tests pass locally
  • Documentation is updated if needed
  • Commit messages follow our convention
  • No merge conflicts with main branch

​
PR Description Template

## Description
Brief description of what this PR does.

## Type of Change
- [ ] Bug fix (non-breaking change which fixes an issue)
- [ ] New feature (non-breaking change which adds functionality)
- [ ] Breaking change (fix or feature that would cause existing functionality to not work as expected)
- [ ] Documentation update

## Testing
- [ ] I have added tests that prove my fix is effective or that my feature works
- [ ] New and existing unit tests pass locally with my changes

## Screenshots (if applicable)
Include screenshots or GIFs showing the changes.

​
Code Review Process

  1. Automated Checks: CI/CD pipeline runs tests and linting
  2. Maintainer Review: Core team members review code quality and design
  3. Community Feedback: Other contributors may provide input
  4. Approval & Merge: Once approved, changes are merged to main

​
Development Tips

Start Small: Begin with small contributions like documentation improvements or bug fixes to get familiar with our workflow.

Ask Questions: Join our Discord if you need help or have questions about contributing.

Stay Updated: Regularly sync your fork with the upstream repository to avoid conflicts.

​
Recognition

Contributors are recognized in:

  • README.md contributors section
  • Release notes for significant contributions
  • Discord contributor role and channels

​
Getting Help

  • Documentation: Check our comprehensive docs
  • Discord: Join our community for real-time help
  • Issues: Search existing issues or create a new one
  • Discussions: Use GitHub Discussions for questions and ideas

Thank you for contributing to GAIA! 🚀