Contributing

Thank you for your interest in contributing to the chipfiring package! We welcome contributions of all kinds from bug reports and feature requests to code contributions and documentation improvements.

Development Setup

To set up the development environment:

# Clone the repository
git clone https://github.com/DhyeyMavani2003/chipfiring.git
cd chipfiring

# Create and activate virtual environment
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Install development dependencies
pip install -r requirements.txt
pip install -r requirements.docs.txt
pip install -e .  # Install in development mode

Running Tests

We use pytest for testing. To run the test suite:

# Run the complete local test suite
python -m pytest -q

# Run specific tests
python -m pytest tests/test_cfgraph.py -q

# Run executable package examples and saved-output checks
python -m pytest --doctest-modules chipfiring -q
make check-example-outputs PYTHON=python

# Run tests across all supported Python versions (requires tox and the
# corresponding Python interpreters)
python -m pip install tox
python -m tox

Building Documentation

The documentation is built using Sphinx:

# Build the documentation from the repository root
make -C docs html

# View the documentation
open docs/_build/html/index.html  # On macOS
# or
xdg-open docs/_build/html/index.html  # On Linux
# or
start docs/_build/html/index.html  # On Windows

Code Style

We follow PEP 8 guidelines for Python code. We use the following tools for code quality:

  • black: For code formatting

  • ruff: For linting

  • mypy: For static type checking

You can run these tools with:

# Format code
black chipfiring/ tests/

# Lint code
ruff check chipfiring/ tests/

# Type check
mypy --check-untyped-defs chipfiring/

Pull Requests

When submitting a pull request:

  1. Fork the repository and create a new branch from main

  2. Add tests for any new functionality

  3. Update documentation as necessary

  4. Ensure all tests pass and code quality checks succeed

  5. Submit a pull request with a clear description of your changes

Issues and Feature Requests

If you find a bug or would like to request a feature, please open an issue on the GitHub repository. When reporting a bug, please include:

  • A clear description of the issue

  • Steps to reproduce the problem

  • Expected behavior

  • Actual behavior

  • Any error messages or stack traces

Code of Conduct

Please be respectful and considerate of others when contributing to this project. We aim to foster an inclusive and welcoming community.