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

# Contributing to OpenTrack

> Guidelines for contributing code, translations, documentation, and bug reports to the OpenTrack project

OpenTrack is an open-source project that welcomes contributions from the community. Whether you're a developer, translator, documentation writer, or user reporting bugs, your contributions help make OpenTrack better for everyone.

## Ways to Contribute

<CardGroup cols={3}>
  <Card title="Code" icon="code">
    Write trackers, filters, protocols, or improve core functionality
  </Card>

  <Card title="Bug Reports" icon="bug">
    Report issues and help identify problems
  </Card>

  <Card title="Documentation" icon="book">
    Write guides, tutorials, and improve documentation
  </Card>

  <Card title="Translations" icon="language">
    Translate OpenTrack to your language
  </Card>

  <Card title="Testing" icon="vial">
    Test new features and pre-release versions
  </Card>

  <Card title="Support" icon="hands-helping">
    Help other users on forums and issue trackers
  </Card>
</CardGroup>

## Getting Started

<Steps>
  <Step title="Read the Documentation">
    Familiarize yourself with OpenTrack:

    * [Quick Start Guide](https://github.com/opentrack/opentrack/wiki/Quick-Start-Guide-\(WIP\))
    * [Hacking OpenTrack](https://github.com/opentrack/opentrack/wiki/Hacking-opentrack) - Core development guide
    * [Plugin API documentation](https://github.com/opentrack/opentrack/blob/master/api/plugin-api.hpp)
  </Step>

  <Step title="Set Up Development Environment">
    Build OpenTrack from source:

    <CardGroup cols={2}>
      <Card title="Building from Source" href="/advanced/building-from-source">
        Complete build instructions for all platforms
      </Card>

      <Card title="Plugin Development" href="/advanced/plugin-development">
        Guide to creating custom plugins
      </Card>
    </CardGroup>
  </Step>

  <Step title="Explore the Codebase">
    Clone the repository and explore:

    ```bash theme={null}
    git clone https://github.com/opentrack/opentrack.git
    cd opentrack
    ```

    **Key directories:**

    * `api/` - Plugin API interfaces
    * `tracker-*/` - Tracker implementations
    * `filter-*/` - Filter implementations
    * `proto-*/` - Protocol implementations
    * `gui/` - Main application UI
    * `cmake/` - Build system
  </Step>

  <Step title="Join the Community">
    * Create a [GitHub account](https://github.com/)
    * Star the [OpenTrack repository](https://github.com/opentrack/opentrack)
    * Watch for updates
  </Step>
</Steps>

## Contributing Code

### Development Workflow

<Steps>
  <Step title="Fork the Repository">
    Create your own fork on GitHub:

    1. Visit [opentrack/opentrack](https://github.com/opentrack/opentrack)
    2. Click "Fork" in the top-right corner
    3. Clone your fork:

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

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

    ```bash theme={null}
    git checkout -b feature/my-new-feature
    ```

    **Branch naming conventions:**

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

  <Step title="Make Your Changes">
    Write your code following the project's style:

    * Use consistent indentation (spaces, not tabs)
    * Follow existing code style
    * Comment complex logic
    * Keep commits focused and atomic
  </Step>

  <Step title="Test Your Changes">
    Build and test thoroughly:

    ```bash theme={null}
    mkdir build
    cd build
    cmake .. -DCMAKE_BUILD_TYPE=RELEASE
    make -j$(nproc)
    make install

    # Test the installed version
    ./install/bin/opentrack
    ```
  </Step>

  <Step title="Commit Your Changes">
    Write clear, descriptive commit messages:

    ```bash theme={null}
    git add .
    git commit -m "tracker/aruco: improve marker detection in low light

    - Adjust adaptive threshold parameters
    - Add contrast enhancement preprocessing
    - Fixes #123"
    ```

    **Good commit messages:**

    * Start with component prefix (`tracker/`, `filter/`, `proto/`, `gui/`)
    * Use imperative mood ("add" not "added")
    * Explain *why*, not just *what*
    * Reference issue numbers with `#123`
  </Step>

  <Step title="Push and Create Pull Request">
    Push your changes and create a PR:

    ```bash theme={null}
    git push origin feature/my-new-feature
    ```

    Then on GitHub:

    1. Navigate to your fork
    2. Click "Pull Request"
    3. Select your branch
    4. Write a detailed description:
       * What problem does it solve?
       * How to test the changes?
       * Any breaking changes?
  </Step>
</Steps>

### Code Style Guidelines

<Tabs>
  <Tab title="C++">
    ```cpp theme={null}
    // Use descriptive variable names
    int camera_width = 640;
    double exposure_time = 0.033;

    // Prefer RAII and modern C++
    {
        std::lock_guard<std::mutex> lock(mutex);
        data = new_data;
    }

    // Use const correctness
    void process_data(const double* input, double* output) const;

    // Document public interfaces
    /**
     * Start the tracker with the given video frame.
     * @param frame Optional widget for displaying video
     * @return status_ok() on success, error() with message on failure
     */
    virtual module_status start_tracker(QFrame* frame) = 0;
    ```
  </Tab>

  <Tab title="CMake">
    ```cmake theme={null}
    # Use otr_module() for plugins
    otr_module(tracker-mytracker)

    # Link required libraries
    target_link_libraries(opentrack-tracker-mytracker
        PRIVATE
            opentrack-api
            opentrack-cv
            ${OpenCV_LIBS}
    )

    # Add include directories if needed
    target_include_directories(opentrack-tracker-mytracker
        PRIVATE
            ${CMAKE_CURRENT_SOURCE_DIR}
    )
    ```
  </Tab>

  <Tab title="Qt">
    ```cpp theme={null}
    // Use Qt's signal/slot mechanism
    connect(ui.button, &QPushButton::clicked,
            this, &MyDialog::onButtonClicked);

    // Use Qt's container classes
    QVector<double> values;
    QString error_message;

    // Support translations
    QString name() override
    {
        return tr("My Tracker");
    }

    // Handle dialog lifecycle
    void MyDialog::save()
    {
        s.threshold = ui.threshold_slider->value();
    }
    ```
  </Tab>
</Tabs>

### Plugin Development Guidelines

When creating new plugins:

<CardGroup cols={2}>
  <Card title="Follow API Conventions">
    * Implement all required virtual methods
    * Return proper status codes
    * Handle errors gracefully
    * Document your API usage
  </Card>

  <Card title="Performance Matters">
    * Don't block in hot paths
    * Use separate threads for computation
    * Profile your code
    * Optimize critical sections
  </Card>

  <Card title="Test Thoroughly">
    * Test on multiple platforms
    * Test error conditions
    * Test resource cleanup
    * Test with various configurations
  </Card>

  <Card title="Provide Configuration">
    * Create intuitive UI dialogs
    * Use sensible defaults
    * Save/load settings properly
    * Support profile import/export
  </Card>
</CardGroup>

## Reporting Bugs

### Before Reporting

<Steps>
  <Step title="Search Existing Issues">
    Check if the bug is already reported:

    * [OpenTrack Issues](https://github.com/opentrack/opentrack/issues)
    * Search closed issues too
  </Step>

  <Step title="Verify It's a Bug">
    Confirm the issue:

    * Test with latest version
    * Try with default settings
    * Test with different profiles
    * Check if it's user error
  </Step>

  <Step title="Gather Information">
    Collect diagnostic information:

    * OpenTrack version (Help → About)
    * Operating system and version
    * Hardware details (CPU, GPU, camera)
    * Steps to reproduce
    * Error messages or logs
  </Step>
</Steps>

### Creating a Bug Report

<Note>
  Don't be afraid to submit an issue! The OpenTrack team is friendly and welcomes bug reports.
</Note>

Create a detailed bug report on [GitHub Issues](https://github.com/opentrack/opentrack/issues/new):

```markdown theme={null}
**Describe the bug**
A clear description of what the bug is.

**To Reproduce**
Steps to reproduce the behavior:
1. Go to '...'
2. Click on '...'
3. Scroll down to '...'
4. See error

**Expected behavior**
What you expected to happen.

**Screenshots**
If applicable, add screenshots.

**Environment:**
 - OS: [e.g. Windows 10 21H2]
 - OpenTrack version: [e.g. 2023.1.0]
 - Tracker: [e.g. PointTracker]
 - Camera: [e.g. Logitech C920]

**Additional context**
Any other context about the problem.
```

## Contributing Documentation

### Wiki Contributions

The OpenTrack wiki is maintained in a [separate repository](https://github.com/opentrack/wiki):

<Steps>
  <Step title="Fork the Wiki Repository">
    ```bash theme={null}
    git clone https://github.com/opentrack/wiki.git
    cd wiki
    ```
  </Step>

  <Step title="Edit Markdown Files">
    Wiki pages are written in Markdown:

    ```markdown theme={null}
    # Page Title

    ## Section

    Content here...

    ### Subsection

    More content...
    ```
  </Step>

  <Step title="Submit Pull Request">
    Send your documentation improvements:

    ```bash theme={null}
    git add .
    git commit -m "docs: add guide for XYZ tracker"
    git push origin master
    ```

    Create a PR to [opentrack/wiki](https://github.com/opentrack/wiki)
  </Step>
</Steps>

<Note>
  The [user-facing wiki](https://github.com/opentrack/opentrack/wiki) automatically updates when commits are merged.
</Note>

## Contributing Translations

OpenTrack supports multiple languages:

### Supported Languages

```cmake theme={null}
set(opentrack_all-translations "de_DE;nl_NL;ru_RU;stub;zh_CN")
```

* **de\_DE** - German
* **nl\_NL** - Dutch
* **ru\_RU** - Russian
* **zh\_CN** - Chinese (Simplified)
* **stub** - Template for new translations

### Translation Workflow

<Steps>
  <Step title="Find Translation Files">
    Translation files are in `lang/` subdirectories:

    ```bash theme={null}
    tracker-aruco/lang/de_DE.ts
    tracker-aruco/lang/nl_NL.ts
    gui/lang/ru_RU.ts
    ```
  </Step>

  <Step title="Edit with Qt Linguist">
    Use Qt Linguist to edit `.ts` files:

    ```bash theme={null}
    linguist tracker-aruco/lang/de_DE.ts
    ```

    Or edit XML directly:

    ```xml theme={null}
    <message>
        <source>Start tracking</source>
        <translation>Tracking starten</translation>
    </message>
    ```
  </Step>

  <Step title="Test Translation">
    Build and test:

    ```bash theme={null}
    cmake .. && make
    LANG=de_DE.UTF-8 ./opentrack
    ```
  </Step>

  <Step title="Submit Translation">
    Create a PR with your translations:

    ```bash theme={null}
    git add */lang/*.ts
    git commit -m "i18n: update German translation"
    git push origin translation-updates
    ```
  </Step>
</Steps>

### Adding a New Language

To add a new language:

1. Add language code to `CMakeLists.txt`:
   ```cmake theme={null}
   set(opentrack_all-translations "de_DE;nl_NL;ru_RU;stub;zh_CN;fr_FR")
   ```

2. Create `.ts` files in each module's `lang/` directory

3. Translate using Qt Linguist

4. Submit PR with new language support

## Testing and QA

### Beta Testing

Help test new features:

1. **Try pre-release builds:**
   * Check [GitHub Actions](https://github.com/opentrack/opentrack/actions) for CI builds
   * Test on your hardware

2. **Report findings:**
   * What works well
   * What doesn't work
   * Performance issues

3. **Suggest improvements:**
   * UI/UX feedback
   * Feature requests
   * Documentation gaps

## Code of Conduct

### Community Guidelines

<CardGroup cols={2}>
  <Card title="Be Respectful" icon="handshake">
    Treat all contributors with respect and professionalism
  </Card>

  <Card title="Be Constructive" icon="comments">
    Provide helpful feedback and constructive criticism
  </Card>

  <Card title="Be Patient" icon="clock">
    Maintainers are volunteers with limited time
  </Card>

  <Card title="Be Collaborative" icon="users">
    Work together to solve problems and improve the project
  </Card>
</CardGroup>

## Recognition

Contributors are recognized in multiple ways:

### Credits

Significant contributors are listed in:

* `AUTHORS.md` - Core contributors
* `README.md` - Credits section
* Module-specific files - Component authors

### Current Contributors

From `AUTHORS.md`:

* **Stanislaw Halik** - Project maintainer
* **Chris Thompson** - Rift and Razer Hydra modules
* **Xavier Hallade** - Intel RealSense tracker
* **Donovan Baarda** - EWMA filter
* **Michael Welter** - Kalman filter
* **Attila Csipa** - S2Bot tracker
* **Wei Shuai** - Wiimote tracker
* **Stéphane Lenclud** - Kinect Face Tracker, Easy Tracker

[See full list](https://github.com/opentrack/opentrack/blob/master/AUTHORS.md)

## License

OpenTrack is licensed under the **ISC license** (permissive open-source):

```
Permission to use, copy, modify, and/or distribute this software for any
purpose with or without fee is hereby granted, provided that the above
copyright notice and this permission notice appear in all copies.
```

By contributing, you agree to license your contributions under the same terms.

<Note>
  See [OPENTRACK-LICENSING.txt](https://github.com/opentrack/opentrack/blob/master/OPENTRACK-LICENSING.txt) for complete licensing information.
</Note>

## Resources

<CardGroup cols={2}>
  <Card title="GitHub Repository" icon="github" href="https://github.com/opentrack/opentrack">
    Main codebase and issue tracker
  </Card>

  <Card title="Wiki" icon="book" href="https://github.com/opentrack/opentrack/wiki">
    User documentation and guides
  </Card>

  <Card title="Plugin API" icon="plug" href="https://github.com/opentrack/opentrack/blob/master/api/plugin-api.hpp">
    Complete API reference
  </Card>

  <Card title="Hacking Guide" icon="code" href="https://github.com/opentrack/opentrack/wiki/Hacking-opentrack">
    Core development guide
  </Card>
</CardGroup>

## Questions?

If you have questions about contributing:

* **Issues:** Ask on [GitHub Issues](https://github.com/opentrack/opentrack/issues)
* **Discussions:** Start a discussion on GitHub
* **Email:** Contact maintainers (see AUTHORS.md)

<Note>
  We're a friendly community and welcome contributions of all sizes. Don't hesitate to get involved!
</Note>