Skip to main content

​
Before You Start

Ensure you have:
  1. Set up your development environment
  2. Read our code style guide
  3. Reviewed existing issues and PRs

​
Creating a Pull Request

1

Fork the Repository

Fork the GAIA repository on GitHub to your account.
2

Clone Your Fork

Clone your fork locally:
git clone https://github.com/YOUR_USERNAME/gaia.git
cd gaia
3

Add Upstream Remote

Add the original repository as upstream:
git remote add upstream https://github.com/theexperiencecompany/gaia.git
4

Create a Feature Branch

Create a new branch for your changes:
git checkout -b feature/your-feature-name
Branch naming conventions:
  • feature/ - New features
  • fix/ - Bug fixes
  • docs/ - Documentation updates
  • refactor/ - Code refactoring
5

Make Your Changes

Make your changes following our code style guide.Test your changes:
mise lint
mise test
6

Commit Your Changes

Commit with a descriptive message following conventional commits:
git add .
git commit -m "feat(scope): description of changes"
7

Sync with Upstream

Keep your branch up to date:
git fetch upstream
git rebase upstream/master
8

Push to Your Fork

Push your changes:
git push origin feature/your-feature-name
9

Create Pull Request

Go to github.com/theexperiencecompany/gaia and create a pull request.

​
Pull Request Guidelines

​
Title Format

Use conventional commit format: 
feat(auth): add OAuth2 support
fix(api): resolve race condition in user creation
docs(readme): update installation instructions

​
Description Template

Include:
  1. What: Brief description of the change
  2. Why: Reason for the change
  3. How: Technical approach taken
  4. Testing: How you tested the changes
  5. Screenshots: If applicable (for UI changes)
  6. Related Issues: Link related issues

​
Checklist

Before submitting, ensure:
  • Code follows style guidelines
  • Self-review completed
  • Comments added for complex logic
  • Documentation updated if needed
  • No new warnings generated
  • Tests added/updated and passing
  • Dependent changes merged
  • Conventional commit format used

​
Review Process

​
What to Expect

  1. Automated Checks: CI/CD runs tests and linters
  2. Code Review: Maintainers review your code
  3. Feedback: Address any requested changes
  4. Approval: Once approved, your PR will be merged

​
Responding to Feedback

  • Be responsive to review comments
  • Ask questions if feedback is unclear
  • Make requested changes promptly
  • Re-request review after updates

​
Making Changes

After feedback: 
# Make your changes
git add .
git commit -m "fix: address review feedback"
git push origin feature/your-feature-name
The PR will automatically update.

​
After Merge

Once merged:
  1. Delete your feature branch: 
    git branch -d feature/your-feature-name
git push origin --delete feature/your-feature-name
  2. Update your local master: 
    git checkout master
git pull upstream master
  3. You’ll be added to our contributors list! 🎉

​
Common Issues

Sync with upstream and resolve conflicts:
git fetch upstream
git rebase upstream/master
# Resolve conflicts
git rebase --continue
git push origin feature/your-feature-name --force
Review the CI logs and fix issues: bash mise lint:fix mise test git add . git commit -m "fix: resolve CI issues" git push
Rebase on latest master:
git fetch upstream
git rebase upstream/master
git push origin feature/your-feature-name --force

​
Getting Help

Need assistance? Thank you for contributing to GAIA! 🚀