> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/trailbaseio/trailbase/llms.txt
> Use this file to discover all available pages before exploring further.

# Contributing

> How to contribute to TrailBase development

Thank you for your interest in contributing to TrailBase! Contributions are very much appreciated and help make TrailBase better for everyone.

<Note>
  For anything beyond bug fixes, please reach out first to discuss your proposal. This helps ensure it aligns with the project roadmap and avoids surprises.
</Note>

## Ways to Contribute

<CardGroup cols={2}>
  <Card title="Report Bugs" icon="bug">
    Found an issue? Report it on GitHub Issues
  </Card>

  <Card title="Suggest Features" icon="lightbulb">
    Have an idea? Share it on GitHub Discussions
  </Card>

  <Card title="Improve Docs" icon="book">
    Help make documentation clearer and more complete
  </Card>

  <Card title="Submit Code" icon="code">
    Fix bugs or implement new features
  </Card>

  <Card title="Answer Questions" icon="comments">
    Help others in GitHub Discussions or Discord
  </Card>

  <Card title="Share Projects" icon="rocket">
    Show what you've built with TrailBase
  </Card>
</CardGroup>

## Getting Started

### Repository Structure

The TrailBase repository contains all components:

```
trailbase/
├── crates/              # Rust crates
│   ├── trail/          # Main server binary
│   ├── trailbase/      # Core library
│   ├── auth-ui/        # Authentication UI WASM component
│   ├── assets/         # Frontend assets (admin UI, etc.)
│   └── ...             # Other crates
├── client/            # Client libraries
│   ├── dart/           # Dart/Flutter client
│   ├── dotnet/         # C#/.NET client
│   ├── go/             # Go client
│   ├── kotlin/         # Kotlin client
│   ├── python/         # Python client
│   ├── rust/           # Rust client
│   └── swift/          # Swift client
├── examples/          # Example projects
├── docs/              # Documentation site
└── deploy/            # Deployment configurations
```

<Info>
  Benchmarks are kept in a [separate repository](https://github.com/trailbaseio/trailbase-benchmark) due to external dependencies.
</Info>

### Development Setup

To build TrailBase from source, you'll need:

#### Prerequisites

* **Rust**: Latest stable toolchain (1.90+)
* **Node.js**: v18+ and pnpm
* **GEOS**: Geospatial library
* **Protobuf**: Protocol buffers compiler
* **Git**: For cloning the repository

#### Building on Linux/macOS

1. **Clone the repository**:
   ```sh theme={null}
   git clone https://github.com/trailbaseio/trailbase.git
   cd trailbase
   ```

2. **Initialize submodules**:
   ```sh theme={null}
   git submodule update --init --recursive
   ```

3. **Install JavaScript dependencies**:
   ```sh theme={null}
   pnpm install
   ```

4. **Build the executable**:
   ```sh theme={null}
   # Debug build (faster compilation)
   cargo build --bin trail

   # Release build (optimized, slower compilation)
   cargo build --bin trail --release
   ```

5. **Run the binary**:
   ```sh theme={null}
   # Debug build
   ./target/debug/trail run

   # Release build
   ./target/release/trail run
   ```

#### Building on Windows

Windows requires enabling symlinks:

```powershell theme={null}
# Enable symlinks (run as administrator or enable developer mode)
git config core.symlinks true
git reset --hard

# Then follow the same steps as Linux/macOS
git submodule update --init --recursive
pnpm install
cargo build --bin trail
```

#### Using Docker for Development

If you don't want to install build dependencies:

```sh theme={null}
# Initialize submodules
git submodule update --init --recursive

# Build using Docker
docker build . -t trailbase
```

### Running Tests

TrailBase has extensive test coverage:

```sh theme={null}
# Run all tests
cargo test

# Run tests for a specific crate
cargo test -p trailbase

# Run tests with output
cargo test -- --nocapture

# Run integration tests
cargo test --test integration_tests
```

### Development Workflow

1. **Create a branch** for your changes:
   ```sh theme={null}
   git checkout -b feature/my-feature
   ```

2. **Make your changes** and test them

3. **Run tests** to ensure nothing breaks:
   ```sh theme={null}
   cargo test
   ```

4. **Check formatting**:
   ```sh theme={null}
   cargo fmt --check
   ```

5. **Run clippy** for linting:
   ```sh theme={null}
   cargo clippy -- -D warnings
   ```

6. **Commit your changes** with clear messages:
   ```sh theme={null}
   git add .
   git commit -m "Add feature: description of changes"
   ```

7. **Push and create a pull request**:
   ```sh theme={null}
   git push origin feature/my-feature
   ```

## Contribution Guidelines

### Code Style

* **Rust**: Follow standard Rust conventions
  * Use `cargo fmt` for formatting
  * Address `cargo clippy` warnings
  * Write idiomatic Rust code
  * Add comments for complex logic

* **TypeScript/JavaScript**:
  * Follow the existing code style
  * Use TypeScript where possible
  * Run prettier for formatting

* **Documentation**:
  * Update docs for new features
  * Include code examples
  * Keep README.md up to date

### Commit Messages

Write clear, descriptive commit messages:

* Use present tense ("Add feature" not "Added feature")
* Keep the first line under 72 characters
* Reference issues when applicable: "Fix #123: description"
* Explain *why* the change was made, not just *what*

**Good examples**:

```
Add geospatial query support for @within operator

Fix authentication timeout issue (#123)

Update client library to support filtered subscriptions
```

### Pull Request Process

1. **Discuss first**: For large changes, open an issue or discussion before starting work

2. **Keep PRs focused**: One feature or fix per PR when possible

3. **Write tests**: Include tests for new functionality

4. **Update documentation**: Document new features and API changes

5. **Describe your changes**: Write a clear PR description explaining:
   * What the change does
   * Why it's needed
   * How it works
   * Any breaking changes

6. **Respond to feedback**: Be open to suggestions and iterate based on review comments

7. **Keep your PR updated**: Rebase on main if needed

### Testing Requirements

* **Unit tests**: For individual functions and modules
* **Integration tests**: For API endpoints and features
* **End-to-end tests**: For critical user workflows
* **Regression tests**: When fixing bugs

All tests must pass before merging:

```sh theme={null}
cargo test
```

### Documentation

Documentation improvements are always welcome:

* **API documentation**: Rustdoc comments for public APIs
* **User guides**: Step-by-step tutorials and examples
* **Reference docs**: Comprehensive feature documentation
* **Code examples**: Practical, working examples
* **Readme updates**: Keep installation and quickstart current

## Contributor License Agreement

TrailBase uses a simple Contributor License Agreement (CLA):

<Warning>
  Before your first contribution can be merged, you'll be asked to sign the CLA.
</Warning>

The CLA ensures:

* **You retain your copyright**: You keep ownership of your contributions
* **Open source forever**: TrailBase will continue to be freely available under an OSI-approved copyleft license
* **Flexibility for the project**: Allows some licensing flexibility (similar to Grafana or Element)
* **Legal clarity**: Protects both contributors and users

### Why a CLA?

The CLA provides flexibility for potential future licensing needs while ensuring TrailBase remains open source. This approach is established by larger successful projects like Grafana and Element.

<Info>
  The exact licensing model is still being refined for optimal compatibility between OSL-3.0 and more popular licenses.
</Info>

## Areas Where Help is Needed

Current priorities for contributions:

### High Priority

* **Documentation improvements**: Tutorials, guides, and examples
* **Bug fixes**: Check [GitHub Issues](https://github.com/trailbaseio/trailbase/issues) for open bugs
* **Test coverage**: Expand test coverage for existing features
* **Client library improvements**: Enhance type safety and ergonomics
* **Mobile admin UI**: Improve mobile experience

### Medium Priority

* **Performance optimizations**: Benchmark and optimize hot paths
* **WASM examples**: More examples of WASM components
* **Deployment guides**: Platform-specific deployment documentation
* **Integration examples**: Examples with popular frameworks
* **Geospatial features**: Expand spatial capabilities

### Feature Requests

* **GraphQL support**: Generate GraphQL alongside REST
* **Additional OAuth providers**: More authentication options
* **Advanced admin features**: Query builder, visual design tools
* **Monitoring integrations**: Better observability

See the [roadmap](/resources/roadmap) for more details on planned features.

## Community Guidelines

### Code of Conduct

Be respectful, inclusive, and constructive:

* **Be welcoming**: Help newcomers and be patient with questions
* **Be respectful**: Disagree gracefully and assume good intentions
* **Be collaborative**: Work together toward better solutions
* **Be constructive**: Provide helpful feedback and alternatives

### Communication Channels

* **GitHub Issues**: Bug reports and feature requests
* **GitHub Discussions**: General questions and community discussion
* **Discord**: Real-time chat with the community
* **Pull Requests**: Code review and technical discussion

### Getting Help

If you need help contributing:

1. Check existing documentation and issues
2. Ask in GitHub Discussions
3. Join the Discord community
4. Tag maintainers in your issue/PR if stuck

Don't hesitate to ask questions!

## Recognition

Contributors are recognized in several ways:

* Listed in the GitHub contributors page
* Mentioned in release notes for significant contributions
* Credit in documentation for major features
* Community recognition on Discord

## Legal and Licensing

By contributing to TrailBase, you agree that:

* Your contributions will be licensed under OSL-3.0 (server) or Apache-2.0 (clients)
* You have the right to submit the contribution
* You sign the CLA for the project

For more about licensing, see the [license page](/resources/license).

## Release Process

<Note>
  This section is informational for contributors. Releases are managed by maintainers.
</Note>

1. **Version bump**: Update version in Cargo.toml files
2. **Update changelog**: Document all changes since last release
3. **Tag release**: Create a git tag for the version
4. **Build binaries**: CI builds and uploads release binaries
5. **Publish packages**: Client libraries published to package registries
6. **Update docs**: Documentation site updated
7. **Announce**: Release announced on GitHub, Discord, and social media

## Resources for Contributors

<CardGroup cols={2}>
  <Card title="GitHub Repository" icon="github" href="https://github.com/trailbaseio/trailbase">
    Source code, issues, and PRs
  </Card>

  <Card title="Discussions" icon="comments" href="https://github.com/trailbaseio/trailbase/discussions">
    Community Q\&A and proposals
  </Card>

  <Card title="Roadmap" icon="map" href="/resources/roadmap">
    Future plans and priorities
  </Card>

  <Card title="Architecture" icon="diagram-project" href="https://github.com/trailbaseio/trailbase/tree/main/docs">
    Technical documentation
  </Card>
</CardGroup>

## First-Time Contributors

New to open source? Welcome! Here's how to get started:

1. **Look for "good first issue" labels** on GitHub Issues
2. **Read the codebase**: Explore the code to understand the structure
3. **Start small**: Begin with documentation or small bug fixes
4. **Ask questions**: Don't hesitate to ask for clarification
5. **Learn from reviews**: Code review is a learning opportunity

### Good First Issues

Look for issues tagged with:

* `good first issue`: Beginner-friendly tasks
* `documentation`: Documentation improvements
* `help wanted`: Issues where maintainers need help

## Questions?

If you have questions about contributing:

* Open a discussion on [GitHub Discussions](https://github.com/trailbaseio/trailbase/discussions)
* Join the Discord community
* Comment on relevant issues

We're here to help! Thank you for contributing to TrailBase 🙏