Contributing to PyIndexNum

We welcome contributions from the community! This document outlines the process for contributing to PyIndexNum.

Development Environment Setup

PyIndexNum uses uv for dependency management. To set up your development environment:

# Clone the repository
git clone https://github.com/paluigi/PyIndexNum.git
cd PyIndexNum

# Install dependencies with uv
uv sync --dev

# Activate the virtual environment
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

Code Quality

We maintain high code quality through:

  • Type annotations: All functions should have complete type hints

  • Documentation: Comprehensive docstrings following NumPy style

  • Testing: Pytest for unit tests with good coverage

  • Linting: Follow PEP 8 style guidelines

Pull Request Guidelines

Structure

When submitting a pull request, please:

  1. Create a feature branch from main:

    git checkout -b feature/your-feature-name

  2. Make focused commits with clear messages:

    feat: add new multilateral index method

- Implement GEKS-Törnqvist index
- Add comprehensive tests
- Update documentation

  3. Test thoroughly:

    # Run all tests
uv run pytest

  4. Update documentation if adding new features

PR Template

Please use this structure for your PR description:

## Description
Brief description of the changes

## Type of Change
- [ ] Bug fix
- [ ] New feature
- [ ] Breaking change
- [ ] Documentation update
- [ ] Code refactoring

## Testing
- [ ] Unit tests added/updated
- [ ] Integration tests pass
- [ ] Documentation builds successfully

## Checklist
- [ ] Code follows project style guidelines
- [ ] All tests pass
- [ ] Documentation updated
- [ ] Type annotations complete
- [ ] No breaking changes without discussion

Areas for Contribution

  • New index methods: Implement additional bilateral or multilateral indices

  • Performance optimizations: Improve computational efficiency

  • Documentation: Enhance examples, tutorials, or API docs

  • Testing: Add more comprehensive test cases

  • Bug fixes: Identify and fix issues

  • Data validation: Improve input validation and error handling

Code Style

  • Follow PEP 8 with 88 character line length

  • Use descriptive variable names

  • Add type hints to all function parameters and return values

  • Write comprehensive docstrings for all public functions

Testing

  • Write unit tests for all new functions

  • Aim for >90% test coverage

  • Test edge cases and error conditions

  • Use parametrized tests for multiple scenarios

Documentation

  • Update API documentation for new functions

  • Add examples for new features

  • Keep README and docs in sync

Questions?

If you have questions about contributing, feel free to:

  • Open an issue for discussion

  • Start a discussion in the GitHub discussions tab

  • Contact the maintainers

Thank you for contributing to PyIndexNum! 🎉