Contributing to QGroundControl

July 3, 2026 · View on GitHub

Thank you for considering contributing to QGroundControl! This guide will help you get started with contributing code, reporting issues, and improving documentation.

AI coding agents (Claude Code, Codex, etc.): see AGENTS.md for the canonical agent-facing guide (golden rules, just build/test commands, definition of done, commit conventions). This document remains the human-facing source of truth for the Architecture Patterns that AGENTS.md links back to.

Table of Contents

  1. Getting Started
  2. How to Contribute
  3. Coding Standards
  4. Testing Requirements
  5. Pull Request Process
  6. License Requirements
  7. Additional Resources

Getting Started

Prerequisites

Before you begin, please:

  1. Read the Developer Guide
  2. Review the Build Instructions
  3. Familiarize yourself with the Architecture Patterns in this guide

Development Environment

  • Language: C++20 with Qt 6.10+ framework
  • Build System: CMake 3.25+
  • Platforms: Windows, macOS, Linux, Android, iOS
  • IDE: Qt Creator (recommended), VS Code, or your preferred IDE
  • Build/test/lint commands: see tools/README.md for the just configure / build / test / lint / check workflow

How to Contribute

Reporting Issues

Before creating a new issue:

  1. Search existing issues to avoid duplicates
  2. Provide complete information:
    • QGroundControl version
    • Operating system and version
    • Detailed steps to reproduce
    • Log files (from ~/.local/share/QGroundControl/)
    • Screenshots or videos if applicable

Create an issue: https://github.com/mavlink/qgroundcontrol/issues

For security vulnerabilities: See our Security Policy for responsible disclosure procedures.

Suggesting Enhancements

Feature requests are welcome! Please:

  1. Check if the feature already exists or has been requested
  2. Explain the use case and benefits
  3. Consider implementation complexity
  4. Be prepared to contribute code if possible

Contributing Translations

QGroundControl uses Crowdin for community translations. See tools/translations/README.md for details on how translations are managed.

Contributing Code

  1. Fork the repository

    git clone https://github.com/YOUR-USERNAME/qgroundcontrol.git
cd qgroundcontrol

  2. Create a feature branch

    git checkout -b feature/my-new-feature

  3. Make your changes following our coding standards

  4. Test your changes thoroughly

    • Run just test (or ctest --output-on-failure -L Unit for the unit-test label only)
    • Test on all relevant platforms when possible
    • Test with both PX4 and ArduPilot if applicable

  5. Commit your changes using Conventional Commits

    git add .
git commit -m "feat: brief description"

  6. Push to your fork

    git push origin feature/my-new-feature

  7. Create a Pull Request from your fork to mavlink/qgroundcontrol:master

Coding Standards

Follow CODING_STYLE.md for naming, formatting, C++20 features, QML style, and logging conventions. Run just lint (or pre-commit run --all-files) before committing.

Architecture Patterns

QGroundControl has several core architecture patterns you must follow. See CODING_STYLE.md for full details with code examples:

  • Fact System: ALL vehicle parameters use Facts — never create custom parameter storage
  • Multi-Vehicle: ALWAYS null-check activeVehicle() before use
  • Firmware Plugin: Use vehicle->firmwarePlugin() for firmware-specific behavior
  • QML Integration: Use QML_ELEMENT/QML_SINGLETON/QML_UNCREATABLE macros, Q_PROPERTY for bindings

Testing Requirements

See test/README.md for the complete testing guide, including base classes, CTest labels, MultiSignalSpy, and coverage.

Key points:

  • Add unit tests for new functionality in test/ mirroring src/ structure
  • Use the UnitTest base class (or VehicleTest, MissionTest, etc.)
  • Run ctest --output-on-failure -L Unit before submitting
  • Test on multiple platforms and both PX4/ArduPilot when applicable

Pre-commit Checks

Run the lint gate before committing (just lint, or pre-commit run --all-files for the full sweep) — see tools/README.md for all available development commands.

Pull Request Process

Before Submitting

  1. Rebase on latest master

    git fetch upstream
git rebase upstream/master

  2. Ensure all tests pass (just check)

  3. Update documentation if needed

  4. Write a clear PR description:

    • What problem does it solve?
    • How was it tested?
    • Breaking changes (if any)
    • Screenshots for UI changes

PR Requirements

  • All CI checks must pass
  • Code follows style guidelines
  • Tests added for new features
  • No unrelated changes
  • Commit messages are clear and descriptive (Conventional Commits, see AGENTS.md)

Review Process

  • Maintainers will review your PR
  • Address feedback in new commits (don't force-push during review)
  • Once approved, a maintainer will merge your PR

After Merging

  • Delete your feature branch
  • Your contribution will appear in the next release
  • Thank you for contributing!

License Requirements

All contributions must be compatible with QGroundControl's dual-license system (Apache 2.0 AND GPL v3). Your code must be original or from a compatible license (BSD, MIT, Apache 2.0).

See COPYING.md for full license details, compatible licenses, and contact information.

Additional Resources

Thank you for contributing to QGroundControl! Your efforts help make drone control accessible to everyone.