# Contributing to numistalib Thank you for your interest in contributing! This guide will help you get started. ## § 1 Getting Started ### § 1.1 Prerequisites - Python 3.13 or higher - `uv` package manager - Git - A Numista API key (for testing) ### § 1.2 Development Setup 0. Fork the repository on GitHub 1. Clone your fork: ```bash git clone https://github.com/YOUR_USERNAME/numistalib.git cd numistalib ``` 1. Install dependencies: ```bash uv sync ``` 1. Create `.env` file: ```bash cp .env.example .env # Add your API key to .env ``` 1. Verify installation: ```bash uv run pytest tests/ -v ``` --- ## § 2 Code Standards ### § 2.1 Important Reading **Read `AGENTS.md` (in repository root) completely before contributing.** This file contains authoritative coding standards including: - Naming conventions - Type hints requirements - Complexity limits - Documentation requirements - Architecture patterns ### § 2.2 Key Rules - Use `uv` for tooling - Full type hints everywhere - NumPy-style docstrings for public APIs - Cognitive complexity ≤ 10 - Cyclomatic complexity ≤ 8 - No `print()` statements (use logging) - Always use exception chaining ### § 2.3 Code Quality Tools Run before committing: ```bash # Lint and format uv run ruff check --fix src/ uv run ruff format src/ # Type checking uv run mypy . uv run pyright . # Complexity checks uv run radon cc src/numistalib/ -a -nb uv run xenon --max-absolute B src/numistalib/ # Tests uv run pytest tests/ -v ``` --- ## § 3 Development Workflow ### § 3.1 Branch Strategy 1. Create a feature branch: ```bash git checkout -b feature/your-feature-name ``` 1. Make your changes 2. Commit with descriptive messages: ```bash git commit -m "Add search by catalogue reference - Implement catalogue parameter in search_types - Add tests for catalogue filtering - Update CLI with --catalogue flag" ``` 1. Push to your fork: ```bash git push origin feature/your-feature-name ``` 1. Create a pull request ### § 3.2 Commit Messages Follow this format: ``` :