> ## Documentation Index
> Fetch the complete documentation index at: https://docs.heygaia.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Pull Request Guide

> Guide to creating and submitting pull requests to GAIA, including branch naming, commit guidelines, and review process.

## Before You Start

Ensure you have:

1. [Set up your development environment](/developers/development-setup)
2. Read our [code style guide](/configuration/code-style)
3. Reviewed [existing issues](https://github.com/theexperiencecompany/gaia/issues) and PRs

## Creating a Pull Request

<Steps>
  <Step title="Fork the Repository">
    Fork the GAIA repository on GitHub to your account.
  </Step>

  <Step title="Clone Your Fork">
    Clone your fork locally:

    ```bash theme={null}
    git clone https://github.com/YOUR_USERNAME/gaia.git
    cd gaia
    ```
  </Step>

  <Step title="Add Upstream Remote">
    Add the original repository as upstream:

    ```bash theme={null}
    git remote add upstream https://github.com/theexperiencecompany/gaia.git
    ```
  </Step>

  <Step title="Create a Feature Branch">
    Create a new branch for your changes:

    ```bash theme={null}
    git checkout -b feature/your-feature-name
    ```

    Branch naming conventions:

    * `feature/` - New features
    * `fix/` - Bug fixes
    * `docs/` - Documentation updates
    * `refactor/` - Code refactoring
  </Step>

  <Step title="Make Your Changes">
    Make your changes following our [code style guide](/configuration/code-style).

    Test your changes:

    ```bash theme={null}
    mise lint
    mise test
    ```
  </Step>

  <Step title="Commit Your Changes">
    Commit with a descriptive message following [conventional commits](/configuration/conventional-commits):

    ```bash theme={null}
    git add .
    git commit -m "feat(scope): description of changes"
    ```
  </Step>

  <Step title="Sync with Upstream">
    Keep your branch up to date:

    ```bash theme={null}
    git fetch upstream
    git rebase upstream/master
    ```
  </Step>

  <Step title="Push to Your Fork">
    Push your changes:

    ```bash theme={null}
    git push origin feature/your-feature-name
    ```
  </Step>

  <Step title="Create Pull Request">
    Go to [github.com/theexperiencecompany/gaia](https://github.com/theexperiencecompany/gaia) and create a pull request.
  </Step>
</Steps>

## 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:

```bash theme={null}
# 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:

   ```bash theme={null}
   git branch -d feature/your-feature-name
   git push origin --delete feature/your-feature-name
   ```

2. Update your local master:

   ```bash theme={null}
   git checkout master
   git pull upstream master
   ```

3. You'll be added to our contributors list! 🎉

## Common Issues

<AccordionGroup>
  <Accordion title="Merge Conflicts">
    Sync with upstream and resolve conflicts:

    ```bash theme={null}
    git fetch upstream
    git rebase upstream/master
    # Resolve conflicts
    git rebase --continue
    git push origin feature/your-feature-name --force
    ```
  </Accordion>

  <Accordion title="Failed CI Checks">
    Review the CI logs and fix issues:

    ```bash theme={null}
    mise lint:fix
    mise test
    git add .
    git commit -m "fix: resolve CI issues"
    git push
    ```
  </Accordion>

  <Accordion title="Outdated Branch">
    Rebase on latest master:

    ```bash theme={null}
    git fetch upstream
    git rebase upstream/master
    git push origin feature/your-feature-name --force
    ```
  </Accordion>
</AccordionGroup>

## Getting Help

Need assistance?

* **Discord**: [Join our community](https://discord.heygaia.io)
* **Discussions**: [GitHub Discussions](https://github.com/theexperiencecompany/gaia/discussions)
* **Issues**: Comment on related issues

Thank you for contributing to GAIA! 🚀