From 59924661cd542c44d923c0c8a02ef892f9c13375 Mon Sep 17 00:00:00 2001 From: Shroominic Date: Sat, 9 Aug 2025 12:54:46 -0300 Subject: [PATCH] comprehensive CONTRIBUTING.md file --- CONTRIBUTING.md | 370 ++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 370 insertions(+) create mode 100644 CONTRIBUTING.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 00000000..5374cd44 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,370 @@ +# 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 +(): + + + +