Contributing

​

Ways to Contribute

​

Getting Started

​

Repository Structure

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

​

Development Setup

​

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

# 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

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

# Build using Docker
docker build . -t trailbase

​

Running Tests

# 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

• 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

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

cargo test

​

Documentation

• 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

• 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?

​

Areas Where Help is Needed

​

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

​

Community Guidelines

​

Code of Conduct

• 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

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

​

Recognition

• 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

• 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

​

Release Process

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

​

First-Time Contributors

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

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

​

Questions?

• Open a discussion on GitHub Discussions
• Join the Discord community
• Comment on relevant issues