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.

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.

Ways to Contribute

Report Bugs

Found an issue? Report it on GitHub Issues

Suggest Features

Have an idea? Share it on GitHub Discussions

Improve Docs

Help make documentation clearer and more complete

Submit Code

Fix bugs or implement new features

Answer Questions

Help others in GitHub Discussions or Discord

Share Projects

Show what you’ve built with TrailBase

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

Benchmarks are kept in a separate repository due to external dependencies.

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:

   git clone https://github.com/trailbaseio/trailbase.git
   cd trailbase
   

2. Initialize submodules:

   git submodule update --init --recursive
   

3. Install JavaScript dependencies:

   pnpm install
   

4. Build the executable:

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

5. Run the binary:

   # Debug build
   ./target/debug/trail run
   
   # Release build
   ./target/release/trail run
   

Building on Windows

Windows requires enabling symlinks:

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

# Initialize submodules
git submodule update --init --recursive

# Build using Docker
docker build . -t trailbase

Running Tests

TrailBase has extensive test coverage:

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

   git checkout -b feature/my-feature
   

2. Make your changes and test them

3. Run tests to ensure nothing breaks:

   cargo test
   

4. Check formatting:

   cargo fmt --check
   

5. Run clippy for linting:

   cargo clippy -- -D warnings
   

6. Commit your changes with clear messages:

   git add .
   git commit -m "Add feature: description of changes"
   

7. Push and create a pull request:

   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:

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

Before your first contribution can be merged, you’ll be asked to sign the CLA.

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.

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

Areas Where Help is Needed

Current priorities for contributions:

High Priority

• Documentation improvements: Tutorials, guides, and examples
• Bug fixes: Check GitHub 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 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.

Release Process

This section is informational for contributors. Releases are managed by maintainers.

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

GitHub Repository

Source code, issues, and PRs

Discussions

Community Q&A and proposals

Roadmap

Future plans and priorities

Architecture

Technical documentation

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
• Join the Discord community
• Comment on relevant issues

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