Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
188 lines (128 loc) · 4.71 KB

CONTRIBUTING.md

File metadata and controls

188 lines (128 loc) · 4.71 KB
Raw

Contributing to GERTIE-Qt

Thank you for your interest in contributing to GERTIE-Qt. This document outlines the process for proposing changes, reporting issues, and contributing code.

Code of Conduct

All contributors are expected to adhere to the Code of Conduct. Please read it before participating.

Getting Started

Prerequisites

  • Raspberry Pi 4B (for hardware testing)
  • Python 3.9+
  • Git
  • Knowledge of PySide6 (for GUI work) or picamera2 (for camera work)

Development Setup

# Clone the repository
git clone https://github.com/your-org/GERTIE_Qt.git
cd GERTIE_Qt

# Create a development branch
git checkout -b feature/your-feature-name

# Install development dependencies
pip3 install --break-system-packages -e .
pip3 install ruff pytest pre-commit

# Install pre-commit hooks (recommended)
pre-commit install

Code Quality Setup (Pre-Commit)

Pre-commit hooks will automatically lint and format your code before each commit:

# Install hooks (one-time)
pre-commit install

# Run checks manually on all files
pre-commit run --all-files

# Uninstall hooks (if needed)
pre-commit uninstall

Contribution Types

Bug Reports

See Bug Report Template.

When reporting a bug, include:

  1. Environment — Pi model, OS version, Python version
  2. Steps to reproduce — Exact sequence that triggers the bug
  3. Expected behavior — What should happen
  4. Actual behavior — What does happen
  5. Logs — Output from journalctl -u gertie-*.service or tail qt_latest.log

Feature Requests

Create a GitHub issue with:

  • Title — Concise one-liner
  • Motivation — Why this feature is needed
  • Use case — Specific scenario it solves
  • Proposed API — How you imagine using it

Code Contributions

Step 1: Fork and Branch

git checkout -b feature/descriptive-name
# or
git checkout -b fix/issue-number

Step 2: Code Standards

  • Python style — PEP 8 (enforced by ruff)
  • Imports — Organize as: stdlib, third-party, local
  • Docstrings — One-liner for functions, full description for classes
  • Type hints — Optional but encouraged for new code

Step 3: Test Locally

Pre-commit hooks run automatically before each commit (if installed). You can also run checks manually:

# Pre-commit hooks will run these automatically
# But you can run them manually anytime:
ruff check .
ruff format .

# Run tests (if applicable)
pytest tests/

# Test on hardware
# Deploy to control1 and run through preflight checklist

Step 4: Commit Message Format

type(scope): brief description

Detailed explanation if needed. Link issues:
Fixes #123
Relates to #456

Types: feat, fix, docs, style, refactor, test, chore

Scopes: gui, node, shared, camera, network, telemetry, tools

Example:

fix(camera): correct IMX477 exposure time range

The exposure time validation was rejecting valid values
in the 340–443µs range. Fixed bounds check to match
hardware capabilities.

Fixes #89

Step 5: Pull Request

Create a pull request with:

  • Title — Same as commit message
  • Description — What changed and why
  • Testing — How you verified the change
  • Hardware tested — Which Pi models and cameras

Step 6: Review & Merge

  • Address code review comments
  • Maintain clean commit history (rebase if needed)
  • Merges require approval from maintainers

Code Review Checklist

All PRs are reviewed for:

  • ✅ Does it fix the stated issue?
  • ✅ Does it break any existing functionality?
  • ✅ Is the code clear and maintainable?
  • ✅ Are there any security concerns?
  • ✅ Does it follow project conventions?
  • ✅ Is it documented?

Reporting Security Issues

Do not create a public GitHub issue for security vulnerabilities.

Instead, email security@example.org with:

  • Description of the vulnerability
  • Steps to reproduce
  • Proposed fix (if you have one)

We will respond within 48 hours and work with you to coordinate disclosure.

See SECURITY.md for more details.

Documentation

Changes to code should include documentation updates:

  • Docstrings — For all functions and classes
  • README.md — If user-facing behavior changes
  • docs/ — For architecture changes
  • INSTALL.md — If deployment procedure changes

Licensing

By contributing, you agree that your contributions are licensed under the same license as the project (MIT).

Questions?

Thank you for contributing!