# Contributing to Routstr Proxy We welcome contributions to Routstr Proxy! This document provides guidelines and instructions for contributing to the project. ## Table of Contents - [Getting Started](#getting-started) - [Development Setup](#development-setup) - [Code Standards](#code-standards) - [Testing](#testing) - [Submitting Changes](#submitting-changes) - [Project Structure](#project-structure) - [Documentation](#documentation) - [Release Process](#release-process) ## Getting Started ### Prerequisites - Python 3.11 or higher - [uv](https://docs.astral.sh/uv/) package manager - Docker and Docker Compose (optional, for integration tests) - Git ### Development Setup 1. **Fork and clone the repository** ```bash git clone https://github.com/YOUR_USERNAME/routstr-proxy.git cd routstr-proxy ``` 2. **Set up the development environment** ```bash make setup ``` This will: - Install `uv` if not already installed - Create a virtual environment - Install all dependencies including dev tools - Install the project in editable mode 3. **Configure environment variables** ```bash cp .env.example .env # Edit .env with your configuration ``` 4. **Verify your setup** ```bash make check-deps make test-unit ``` ## Code Standards ### Python Style Guide We use modern Python 3.11+ features and enforce strict type checking: - **Type Hints**: All functions must have complete type annotations ```python # ✅ Good def calculate_cost(tokens: int, price_per_token: float) -> dict[str, float]: return {"total": tokens * price_per_token} # ❌ Bad def calculate_cost(tokens, price_per_token): return {"total": tokens * price_per_token} ``` - **Type Syntax**: Use Python 3.11+ lowercase types ```python # ✅ Good def process_items(items: list[dict[str, str | None]]) -> dict[str, int]: ... # ❌ Bad from typing import List, Dict, Optional def process_items(items: List[Dict[str, Optional[str]]]) -> Dict[str, int]: ... ``` - **Comments**: Only add comments for non-obvious logic. Code should be self-documenting ```python # ✅ Good - complex business logic explained # Apply exponential backoff with jitter to prevent thundering herd delay = min(base_delay * (2 ** attempt) + random.uniform(0, 1), max_delay) # ❌ Bad - obvious comment # Increment counter by 1 counter += 1 ``` ### Code Quality Tools We enforce code quality using: - **Ruff**: For linting and formatting ```bash make lint # Check for issues make format # Auto-fix formatting ``` - **Mypy**: For type checking ```bash make type-check ``` ### Commit Messages Follow the [Conventional Commits](https://www.conventionalcommits.org/) specification: ```text ():