Contributing to SkySpy

Welcome to the SkySpy contributor community! We're thrilled you're interested in helping build the future of aircraft tracking.

New to Contributing? This guide covers everything you need to know, from setting up your environment to getting your first PR merged.

Quick Start

SkySpy Repository

Ways to Contribute

• Bug Reports - Found an issue? Let us know!
• Feature Ideas - Have a great idea? We'd love to hear it!
• Code - Submit PRs for bug fixes or new features
• Documentation - Help improve our docs
• Testing - Write tests and improve coverage
• Code Review - Review open pull requests

Project Architecture

SkySpy is a sophisticated real-time ADS-B aircraft tracking platform with multiple components:

Component	Technology	Location	Badge
Backend API	Django 5.0+ / Django Channels	skyspy_django/
Web Dashboard	React 18 / Vite 5	web/
CLI Tools	Go 1.23+	skyspy-go/
Shared Libraries	Python	skyspy_common/
Mock Services	Docker	test/

Before You Start

Warning: Prerequisites Checklist

• Read through this contributing guide
• Check existing issues and PRs for similar work
• For major changes, open an issue first to discuss
• Sign off on the Developer Certificate of Origin (DCO)

Development Environment Setup

Step 1: Install Prerequisites

Step 2: Clone & Configure

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

# Copy environment template
cp .env.example .env

Essential Environment Variables

Edit .env with your configuration:

Bash

# Required: Feeder location (your antenna position)
FEEDER_LAT=47.9377
FEEDER_LON=-121.9687

# Required: ADS-B receiver host
ULTRAFEEDER_HOST=ultrafeeder
ULTRAFEEDER_PORT=80

# For development, use public auth mode
AUTH_MODE=public

Full Configuration

The .env.example file contains extensive documentation for all available options including authentication, OIDC SSO, notifications, transcription, and external data sources.

Step 3: Database Setup

Recommended: Docker Setup

The development environment automatically provisions PostgreSQL and Redis:

Bash

# Start all services including database
make dev

# Database is automatically migrated on startup

# Set your database URL
export DATABASE_URL=postgresql://user:password@localhost:5432/skyspy

# Run migrations
cd skyspy_django
python manage.py migrate

Step 4: Start Development Services

# Start full development environment with mock data
make dev

# Services available:
#   Dashboard:     http://localhost:3000
#   Django API:    http://localhost:8000
#   PostgreSQL:    localhost:5432 (via pgbouncer)
#   Redis:         localhost:6379
#   Ultrafeeder:   http://localhost:18080
#   Dump978:       http://localhost:18081

# View logs
make dev-logs

# Stop services
make dev-down

cd skyspy_django

# Create virtual environment
python -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

# Install dependencies
pip install -e ../skyspy_common
pip install -r requirements.txt

# Run migrations
python manage.py migrate

# Start development server
python manage.py runserver 0.0.0.0:8000

# Or with Daphne for Socket.IO support
daphne -b 0.0.0.0 -p 8000 skyspy.asgi:application

# In a separate terminal
cd skyspy_django
celery -A skyspy worker --loglevel=info --pool=gevent --concurrency=10

# In a separate terminal
cd skyspy_django
celery -A skyspy beat --loglevel=info

cd web

# Install dependencies
npm install

# Start development server
npm run dev

# Dashboard available at http://localhost:3000

cd skyspy-go

# Download dependencies
make deps

# Build binary
make build

# Run
./bin/skyspy --help

Code Style Guidelines

Python (Backend)

Configuration (pyproject.toml)

TOML

[tool.ruff]
target-version = "py312"
line-length = 120

[tool.black]
target-version = ["py312"]
line-length = 120

Key Rules:

• Line length: 120 characters maximum
• Use type hints for function signatures
• Follow PEP 8 naming conventions
• Avoid unused imports and variables
• Use isort-compatible import ordering

# Check for issues
ruff check .
black --check --diff .
mypy --ignore-missing-imports .

# Auto-fix issues
ruff check --fix .
black .

JavaScript/React (Frontend)

{
  "semi": true,
  "singleQuote": true,
  "tabWidth": 2,
  "trailingComma": "es5",
  "printWidth": 100,
  "bracketSpacing": true,
  "arrowParens": "always",
  "endOfLine": "lf"
}

ESLint Rules:

• React Hooks rules enforced (rules-of-hooks, exhaustive-deps)
• No console.log (use console.warn or console.error)
• Prefer const over let
• Use strict equality (===)

cd web

# Check for issues
npm run lint
npm run format:check

# Auto-fix issues
npm run lint:fix
npm run format

Go (CLI)

Enabled Linters:

cd skyspy-go

# Run all linters
make lint

# Format code
make fmt

# Check formatting
make fmt-check

# Run go vet
make vet

Git Workflow

Branch Strategy

gitGraph
    commit id: "main"
    branch develop
    checkout develop
    commit id: "integration"
    branch feature/new-alerts
    checkout feature/new-alerts
    commit id: "add alerts"
    commit id: "add tests"
    checkout develop
    merge feature/new-alerts
    branch fix/socketio-bug
    checkout fix/socketio-bug
    commit id: "fix bug"
    checkout develop
    merge fix/socketio-bug
    checkout main
    merge develop tag: "v2.6.0"

Creating a Branch

# Update your local main
git checkout main
git pull origin main

# Create a feature branch
git checkout -b feature/amazing-feature

# Or for bug fixes
git checkout -b fix/bug-description

Commit Messages

Follow Conventional Commits for clear history:

<type>(<scope>): <description>

[optional body]

[optional footer]

Commit Types

Commit Examples

# Feature
git commit -m "feat(alerts): add proximity alert distance configuration"

# Bug fix
git commit -m "fix(socketio): handle reconnection on network timeout"

# Documentation
git commit -m "docs(api): update alert rule endpoint examples"

# Refactoring
git commit -m "refactor(services): extract safety monitoring logic"

Pull Request Process

PR Workflow

flowchart LR
    A[Make Changes] --> B[Run Tests]
    B --> C[Push Branch]
    C --> D[Create PR]
    D --> E[CI Checks]
    E --> F{Pass?}
    F -->|No| A
    F -->|Yes| G[Code Review]
    G --> H{Approved?}
    H -->|No| A
    H -->|Yes| I[Merge]

PR Checklist

Warning: Before Submitting Your PR

• All tests pass locally (make test)
• Code follows project style guidelines
• Documentation updated (if needed)
• No console.log or debug code
• No hardcoded secrets or credentials
• Code is performant (no N+1 queries)
• New functionality has tests

Running Tests Before PR

# Full test suite in Docker (recommended)
make test

# Backend tests only
cd skyspy_django && pytest

# Frontend linting
cd web && npm run lint

# Go tests
cd skyspy-go && make test

# Python
ruff check . && black --check .

# JavaScript
cd web && npm run lint && npm run format:check

# Go
cd skyspy-go && make lint

PR Description Template

## Summary

Brief description of changes and motivation.

## Changes

- Bullet points of specific changes
- Include file paths for major modifications

## Testing

- [ ] Unit tests added/updated
- [ ] Integration tests pass
- [ ] Manual testing completed

## Documentation

- [ ] Code comments updated
- [ ] README/docs updated (if applicable)
- [ ] API documentation updated (if applicable)

## Screenshots (if UI changes)

Before/after screenshots for visual changes.

PR Requirements

Code Review Process

Review Flow

flowchart TB
    subgraph Author
        A1[Submit PR] --> A2[Address Feedback]
        A2 --> A3[Push Updates]
    end

    subgraph Reviewer
        R1[Review Code] --> R2{Issues Found?}
        R2 -->|Yes| R3[Request Changes]
        R2 -->|No| R4[Approve PR]
    end

    subgraph CI
        C1[Run Tests] --> C2[Run Linters]
        C2 --> C3[Security Scan]
    end

    A1 --> R1
    A1 --> C1
    R3 --> A2
    A3 --> R1
    R4 --> M[Merge]
    C3 --> M

For Authors

Before Requesting Review

• Code follows project style guidelines
• All tests pass locally
• New functionality has tests
• Documentation updated
• No debug code or console.log statements
• No hardcoded secrets or credentials
• Error handling is appropriate
• Code is performant (no N+1 queries)

For Reviewers

Review Checklist

Functionality

• Code does what it claims to do
• Edge cases are handled
• Error conditions handled gracefully

Code Quality

• Code is readable and maintainable
• No code duplication
• Functions are focused and appropriately sized

Testing

• Tests are meaningful and comprehensive
• Test coverage is adequate

Security

• No SQL injection vulnerabilities
• No XSS vulnerabilities
• Auth/authz is correct

Warning: Review Etiquette

• Be constructive and specific
• Explain the "why" behind suggestions
• Distinguish between required changes and suggestions
• Approve when satisfied, request changes when needed

Issue Guidelines

Bug Reports

Bug Report Template

Title: [BUG] Brief description

Include:

• Environment (OS, Docker version, Browser)
• SkySpy version or commit hash
• Steps to reproduce
• Expected vs actual behavior
• Relevant logs/screenshots

Feature Requests

Feature Request Template

Title: [FEATURE] Brief description

Include:

• Problem statement
• Proposed solution
• Alternatives considered
• Mockups or examples (if applicable)

Issue Labels

Release Process

Semantic Versioning

flowchart LR
    subgraph Version[" "]
        direction TB
        M[MAJOR x.0.0] --- |Breaking changes| M1[API incompatible]
        N[MINOR 0.x.0] --- |Features| N1[Backward compatible]
        P[PATCH 0.0.x] --- |Fixes| P1[Backward compatible]
    end

CI/CD Pipeline

flowchart LR
    subgraph Trigger
        PR[PR/Push]
        Tag[Git Tag]
    end

    subgraph Tests
        UT[Unit Tests]
        LT[Lint]
        E2E[E2E Tests]
        SEC[Security Scan]
    end

    subgraph Deploy
        BUILD[Build Images]
        PUSH[Push to GHCR]
    end

    PR --> UT --> LT --> E2E --> SEC
    Tag --> BUILD --> PUSH

Docker Images

Published Images

• ghcr.io/{org}/skyspy - Main API image
• ghcr.io/{org}/skyspy-rtl-airband-uploader - RTL-Airband uploader
• ghcr.io/{org}/skyspy-1090-mock - Mock ADS-B receiver
• ghcr.io/{org}/skyspy-acarshub-mock - Mock ACARS hub

Quick Reference

Common Commands

Service URLs (Development)

Community Guidelines

Be Welcoming

We welcome contributors of all experience levels. Everyone was new once!

Be Respectful

Treat everyone with respect. Constructive criticism is welcome; personal attacks are not.

Warning: Communicate Clearly

When in doubt, over-communicate. Ask questions if something is unclear.

Getting Help

Thank You!

Thank you for contributing to SkySpy! Your contributions help make aircraft tracking better for everyone.