Contributing¶

We welcome contributions to pranaam! This guide will help you get started.

Code of Conduct¶

The project welcomes contributions from everyone! It depends on it. To maintain this welcoming atmosphere and to collaborate in a fun and productive way, we expect contributors to the project to abide by the Contributor Code of Conduct.

Getting Started¶

Development Setup¶

Fork the repository on GitHub

Clone your fork locally:

git clone https://github.com/yourusername/pranaam.git
cd pranaam

Create a virtual environment:

python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

Install development dependencies:
```
pip install -e .[dev,test,docs]
```
Install pre-commit hooks:
```
pre-commit install
```

Development Workflow¶

Code Quality Standards¶

We maintain high code quality standards:

Type Safety: 100% MyPy compliance required
Code Formatting: Black formatting (line length 88)
Testing: Comprehensive test coverage
Documentation: All public APIs must be documented

Running Tests¶

Run the full test suite:

pytest

Run specific test categories:

pytest -m unit          # Unit tests only
pytest -m integration   # Integration tests only
pytest -m "not slow"    # Skip slow tests

Run with coverage:

pytest --cov=pranaam --cov-report=html

Code Quality Checks¶

Format code with Black:

black pranaam/

Type check with MyPy:

mypy pranaam/

Both commands must pass without errors before submitting a PR.

Types of Contributions¶

Bug Reports¶

When reporting bugs, please include:

Python version and operating system
TensorFlow version
Complete error traceback
Minimal code example to reproduce the issue
Expected vs. actual behavior

Feature Requests¶

Before submitting feature requests:

Check existing issues and discussions
Provide clear use case and rationale
Consider implementation complexity
Discuss API design implications

Code Contributions¶

Areas where we welcome contributions:

New Language Support: Adding support for additional Indian languages
Model Improvements: Better accuracy or efficiency
Performance Optimizations: Faster prediction times
Documentation: Improved examples and guides
Testing: Additional test cases and edge cases
Bug Fixes: Resolving reported issues

Submission Guidelines¶

Pull Request Process¶

Create a feature branch:

git checkout -b feature/your-feature-name

Make your changes following our coding standards
Add or update tests as needed
Update documentation if applicable

Ensure all tests pass:

pytest
black --check pranaam/
mypy pranaam/

Commit your changes with clear commit messages
Push to your fork and submit a pull request

Pull Request Requirements¶

Your PR must:

Pass all CI checks (tests, linting, type checking)
Include appropriate tests for new functionality
Update documentation for API changes
Follow semantic versioning principles
Include a clear description of changes

Code Style Guidelines¶

Python Code Style¶

Follow PEP 8 with Black formatting
Use type hints for all function signatures
Write docstrings for all public functions and classes
Maximum line length: 88 characters
Use meaningful variable and function names

Documentation Style¶

Use Markdown (.md) format
Include code examples for new features
Write clear, concise explanations
Update API documentation for code changes

Testing Guidelines¶

Write unit tests for all new functions
Include integration tests for complex features
Test edge cases and error conditions
Mock external dependencies appropriately
Aim for high test coverage (>90%)

Project Structure¶

Understanding the Codebase¶

pranaam/
├── __init__.py              # Package initialization
├── naam.py                  # Core Naam class with pred_rel method
├── base.py                  # Base class for model data management
├── utils.py                 # Utility functions
├── logging.py               # Centralized logging configuration
├── pranaam.py              # CLI entry point and function exports
└── tests/                  # Comprehensive test suite
    ├── conftest.py         # pytest fixtures
    ├── test_naam.py        # Core functionality tests
    ├── test_integration.py # End-to-end integration tests
    └── ...                 # Additional test modules

Key Components¶

naam.py: Core prediction logic and model loading
base.py: Model data management using importlib.resources
utils.py: Helper functions for data processing
logging.py: Centralized logging configuration
tests/: Comprehensive test suite with 75+ tests

Release Process¶

Version Management¶

We follow semantic versioning (MAJOR.MINOR.PATCH):

MAJOR: Breaking API changes
MINOR: New features, backward compatible
PATCH: Bug fixes, backward compatible

Release Checklist¶

Before releasing a new version:

Update version in pyproject.toml
Update CLAUDE.md with changes and test status
Run full test suite: pytest (must be 75/75 passing)
Check formatting: black --check pranaam/
Type check: mypy pranaam/ (must pass with zero errors)
Build package: python -m build
Validate: python -m twine check dist/*
Test in clean environment
Verify CI passes on GitHub Actions

Communication¶

Getting Help¶

GitHub Issues: Bug reports and feature requests
GitHub Discussions: General questions and ideas
Documentation: Check our comprehensive docs first

Maintainer Response¶

We aim to:

Acknowledge issues within 48 hours
Review pull requests within 1 week
Provide constructive feedback
Maintain respectful, professional communication

Recognition¶

Contributors are recognized in:

Release notes for significant contributions
AUTHORS.md file (if we create one)
GitHub contributors page

Thank you for contributing to pranaam! Your efforts help make this tool better for researchers, activists, and developers working to understand and address bias in AI systems.