Thank you for considering contributing to this project! This document provides guidelines and instructions for contributing.

By participating in this project, you agree to abide by the Code of Conduct.

• Check existing issues to avoid duplicates
• Use the issue templates when reporting bugs or requesting features
• Provide as much detail as possible to help reproduce and resolve issues

• Python 3.13 or higher
• uv for dependency management
• Git for version control

This project uses EditorConfig to maintain consistent coding styles. Find plugin for your editor at editorconfig.org

This project uses pre-commit to enforce code quality checks before each commit.

• Code formatting with Ruff
• Type checking with Ty
• Python syntax checking
• Security vulnerability scanning
• Trailing whitespace removal
• Merge conflict detection
• Large file detection
• And more (see .pre-commit-config.yaml)

1. Fork and clone the repository

2. Set up your development environment

   # Initialize the project (install dependencies and pre-commit hooks)
   make init

3. Create a branch for your changes

   git checkout -b feature/your-feature-name

4. Make your changes

• Write tests for new functionality
• Update documentation as needed
• Ensure your code follows the project's style guidelines

5. Run checks and tests

   # Format code
   make format
   
   # Run linters
   make lint
   
   # Run tests
   make test
   
   # Run pre-commit hooks on all files
   make precommit
   
   # Run all checks (precommit + test)
   make check

6. Commit your changes

   Use clear and descriptive commit messages following Gitmoji conventions:

   ✨ Add new feature X
   🐛 Fix issue with Y
   📝 Update installation instructions
   ✅ Add tests for feature Z
   ⬆️ Update dependencies
   

7. Push to your fork

   git push origin feature/your-feature-name

8. Submit a Pull Request

• Fill out the PR template
• Reference any related issues
• Wait for review and address any feedback

This project includes a Makefile with useful commands for development:

# Display all available commands
make help

This project follows these conventions:

• Code formatting with ruff
• Type checking with ty
• Type annotations for all functions
• Documentation using Google style docstrings
• Tests written with pytest

This project uses MkDocs for documentation. The documentation source files are in the docs/ directory in Markdown format.

When adding or changing features, please update the documentation accordingly:

• Update docstrings for public functions, classes, and modules
• Update the README.md if needed
• Add examples for new features

• All new features should include tests
• Bug fixes should include tests that demonstrate the issue is fixed
• Run the full test suite before submitting a PR

• Maintainers will review PRs as they are submitted
• Address review comments and update your PR as needed
• Once approved, maintainers will merge your PR

• This project follows Semantic Versioning
• Changes are documented in the CHANGELOG.md

Thank you for contributing!