CONTRIBUTING.md

Contributing to Charon

We appreciate your interest in contributing to Charon!

Quick Links

• Complete Contributing Guide - Detailed development workflow, code standards, and PR process.
• Architecture Overview - In-depth understanding of Charon's architecture.
• Code Standards - Standards for Terraform and Python code.
• Testing Guide - Guidelines for testing changes.

Quick Start for Contributors

1. Fork and clone the repository
2. Set up your development environment (see below)
3. Read the architecture docs to understand the system
4. Make your changes following our code standards
5. Test thoroughly before submitting
6. Submit a pull request with clear description

Development Environment Setup

Option 1: Conda Environment (Recommended)

Charon includes a complete conda environment with all required tools:

# Create the conda environment
conda env create -f environment.yml

# Activate the environment
conda activate charon

# Or update existing environment
conda env update --file environment.yml --prune

The conda environment includes:

• Python 3.11 with all dependencies
• Terraform for infrastructure management
• Pre-commit hooks and code quality tools (ruff, mypy, flake8)
• Testing framework (pytest) and security scanners (checkov, safety)

Option 2: Dev Container

Open the project in VS Code with Dev Containers extension - includes all tools pre-configured.

Branching Strategy

Use descriptive branch names following this convention:

| Branch Type | Format | Example | |-------------|--------|---------| | Feature | feat/description or feature/description | feat/add-grafana-tempo-datasource | | Bug Fix | fix/description | fix/grafana-dashboard-metrics | | Documentation | docs/section | docs/update-grafana-service | | Refactoring | refactor/component | refactor/terraform-variable-names | | Testing | test/component | test/add-prometheus-scrape-tests |

Branching Guidelines:

• Use lowercase with hyphens for readability
• Keep names descriptive but concise (< 50 characters)
• Start with category prefix (feat/, fix/, docs/, etc.)
• Create branches from main for new work
• Rebase frequently to stay current with main

Key Documentation

Architecture & Patterns

• Multi-Container StatefulSet Pattern - Standard deployment pattern with lifecycle automation
• Dependency Tree Management - Terraform dependency best practices
• Networking - VPN mesh, DNS, ingress
• Security - TLS, RBAC, secrets

Development Guides

• Adding New Services - How to add services to Charon
• VPN Enrollment - Connect devices to the VPN
• DNS Management - Automated DNS with Cloudflare
• Certificate Management - Let's Encrypt with cert-manager

Reference Documentation

• Terraform Variables - Complete variable reference
• Environment Variables - .env configuration
• Scripts Reference - Automation scripts documentation

Code Standards Summary

Terraform

• Use count for optional resources: count = var.service_enabled ? 1 : 0
• Never use [0] indexing in depends_on - Terraform handles count automatically
• Follow Dependency Patterns
• Run terraform fmt -recursive before committing

Python

• PEP 8 compliance
• Type hints for all functions
• Docstrings for public APIs
• Proper error handling

See Code Standards for complete details.

Getting Help

• Documentation: Full Documentation Index
• Issues: Found a bug? Open an issue
• Questions: Check Troubleshooting Guide

License

MIT License - see LICENSE file for details.

---

For complete contributing guidelines, see docs/development/contributing.md