CONTRIBUTING.md

How to contribute to the ArduPilot Methodic Configurator project?

We have a very active (and friendly) developer group and would love to have the help! Possible ways you can help:

• Testing the code
• Filing issues on github, when you see a problem or adding detail to existing issues
• Fixing issues
• Adding new features
• Reviewing existing pull requests, and notifying the maintainer if it passes your code review.
• Translating the software into your language
• Finding and fixing security issues

Learning the Code

Read our architecture to get a better understanding of the project.

and also:

• System requirements
• Compliance, including our Coding Standards

Setting up developer environment

1. Install git on your computer.

2. Create a free personal github account

3. Log in to your github account using a browser

4. Fork the ArduPilot/MethodicConfigurator github repository.

5. Clone your fork and navigate into it:

   git clone https://github.com/YOUR_USER_NAME/MethodicConfigurator.git
   cd MethodicConfigurator

6. Run the following helper scripts:

   On Windows:

   .\SetupDeveloperPC.bat

   On Linux and macOS:

   ./SetupDeveloperPC.sh

The above scripts will:

• Configure Git and useful aliases
• Create a Python virtual environment and install project dependencies
• Install recommended VSCode extensions
• Set up pre-commit hooks for linting and formatting
• Install GNU gettext tools for internationalization support

Alternative: Using Docker for Development

As an alternative to setting up the development environment locally, you can use Docker to run the project in a containerized environment. This ensures consistency across different machines and simplifies dependency management.

Prerequisites

• Install Docker on your computer
• Install Docker Compose (usually included with Docker Desktop)

Building and Running

1. Clone the repository and navigate into it:

   git clone https://github.com/YOUR_USER_NAME/MethodicConfigurator.git
   cd MethodicConfigurator

2. Build the Docker image:

   docker compose build

3. Run the development environment:

   To start an interactive shell in the container:

   docker compose run --rm dev

   To run tests:

   docker compose run --rm test

   To run SITL (Software In The Loop) integration tests:

   docker compose run --rm sitl

   To run linters:

   docker compose run --rm lint

Benefits of Docker Development

• Consistent environment across all contributors
• No need to install Python, dependencies, or tools locally
• Isolated from your system's Python installation
• Easy to test against different Python versions by changing the Dockerfile
• Faster onboarding for new contributors

Executing the code

You can either install the Methodic Configurator as a package or run it locally from your development codebase. Installing the package will fetch the latest stable release version — see the installation guide for details.

To run it locally (from your cloned repository):

On Windows:

.venv\Scripts\activate.ps1
python -m ardupilot_methodic_configurator

On macOS & Linux:

source .venv/bin/activate
python3 -m ardupilot_methodic_configurator

More detailed usage instructions can be found in our user manual

Submitting patches

Follow the Conventional Commits style for your git commit messages.

Each commit should be signed off using the --signoff option in git commit. By signing off your commit, you certify that you agree to the terms of the Developer Certificate of Origin (DCO).

You can sign by either your commit by pressing the sign-off button on git gui or by using the command line:

# Sign off a commit as you're making it
git commit --signoff -m "commit message"

# Add a signoff to the last commit you made
git commit --amend --signoff

# Rebase your branch against master and sign off every commit in your branch
git rebase --signoff master

Once your changes are ready, submit a GitHub Pull Request (PR).

Code review process

Once your pull request is submitted, a thorough code review process will begin. We evaluate contributions based on multiple criteria to ensure quality, security, and maintainability. The review includes both automated checks and manual inspection.

Review Process

1. Initial Automated Review: CI checks must pass before manual review begins
2. Peer Review: At least one maintainer reviews the code, adding comments and suggestion to the github pull request webpage
3. Feedback & Iteration: Contributors address review comments and update the PR
4. Final Approval: Maintainers approve and merge the changes
5. Post-Merge: Automated deployment and monitoring ensure stability

Automated Checks

• CI/CD Workflows: All changes are automatically tested against our code quality guidelines and security requirements
• Linting and Formatting: Code must pass Ruff, Pylint, and other quality checks
• Type Checking: MyPy and Pyright validation
• Security Scanning: Automated vulnerability detection via CodeQL and dependency reviews
• Testing: Comprehensive test suite execution with pytest
• Git branching conventions: Is the pull request branch free of merge commits?

Manual Review Criteria

We manually verify the following aspects:

Code Quality & Standards

• Does the code follow our coding standards and PEP 8 guidelines?
• Is the code well-documented with appropriate docstrings and comments?
• Does it include comprehensive error handling and logging?
• Are there any code smells, technical debt, or maintainability issues?
• Do the git commit messages follow conventional commit standards?
• Is at least the last commit in the pull request branch signed off by the contributor?
• Does the pull request have a clear description of the changes and their rationale?

Architecture & Design

• Does the change follow our architecture guidelines?
• Is there proper separation of concerns (backend, business logic, frontend/GUI)?
• Is the code modular, testable, and maintainable?
• Does it follow object-oriented design principles and clean code practices?

Functionality & Testing

• Is it generic enough to be useful for multiple use cases?
• Does the change include appropriate unit tests and integration tests?
• Are edge cases and error conditions properly tested?
• Does it maintain or improve test coverage?
• Have manual testing scenarios been considered?

Security & Compliance

• Does the change follow secure coding practices?
• Does it comply with our license requirements and REUSE specification?

User Experience & Documentation

• Does the change maintain or improve usability?
• Is user-facing documentation updated (including translations)?
• Are there any breaking changes that need documentation?
• New strings must be properly internationalized with _( ... )

Community & Process

• Does the change violate our code of conduct?

Development Team

The ArduPilot Methodic Configurator project is open-source and maintained by a team of volunteers.

New developers are recommended to join the #general and #methodic_configurator channels on Discord.

You can also join the development discussion on Discourse.

Note that these are NOT for user tech support, and are moderated for new users to prevent off-topic discussion.