Contributing to customhys

Thank you for your interest in contributing to customhys! This document provides guidelines and instructions for contributing.

Development Setup

  1. Fork and clone the repository

    git clone https://github.com/YOUR_USERNAME/customhys.git
cd customhys

  2. Create a virtual environment

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

  3. Install development dependencies

    make setup-dev
# or manually:
pip install -e ".[dev,ml,examples]"
pre-commit install

Development Workflow

Code Quality

We use several tools to maintain code quality:

  • Black: Code formatting (line length: 120)

  • Ruff: Fast linting and code quality checks

  • MyPy: Static type checking

  • Pytest: Testing framework

Run all checks before committing:

make check-all

Or run individually:

make format      # Format code with black
make lint        # Check code with ruff
make typecheck   # Type check with mypy
make test        # Run tests

Pre-commit Hooks

Pre-commit hooks will run automatically before each commit:

pre-commit install  # Install hooks
pre-commit run --all-files  # Run manually

Testing

Write tests for new features and bug fixes:

make test        # Run tests with coverage
make test-fast   # Run tests without coverage

Tests should be placed in the tests/ directory.

Making Changes

  1. Create a new branch

    git checkout -b feature/your-feature-name
# or
git checkout -b fix/bug-description

  2. Make your changes

    • Write clear, documented code

    • Add tests for new functionality

    • Update documentation as needed

  3. Run checks

    make check-all
make test

  4. Commit your changes

    git add .
git commit -m "Clear description of your changes"

  5. Push and create a Pull Request

    git push origin your-branch-name

Coding Standards

Python Style

  • Follow PEP 8 guidelines

  • Maximum line length: 120 characters

  • Use type hints where appropriate

  • Write docstrings for all public functions/classes

Documentation

  • Update README.md if adding new features

  • Document all public APIs

  • Include examples for complex functionality

Commit Messages

  • Use clear, descriptive commit messages

  • Start with a verb in present tense (e.g., β€œAdd”, β€œFix”, β€œUpdate”)

  • Reference issue numbers when applicable

Project Structure

customhys/
β”œβ”€β”€ customhys/           # Main package
β”‚   β”œβ”€β”€ __init__.py
β”‚   β”œβ”€β”€ benchmark_func.py
β”‚   β”œβ”€β”€ experiment.py
β”‚   β”œβ”€β”€ hyperheuristic.py
β”‚   β”œβ”€β”€ metaheuristic.py
β”‚   β”œβ”€β”€ operators.py
β”‚   β”œβ”€β”€ population.py
β”‚   β”œβ”€β”€ tools.py
β”‚   └── visualisation.py
β”œβ”€β”€ tests/               # Test files
β”œβ”€β”€ examples/            # Example notebooks and scripts
β”œβ”€β”€ docfiles/            # Documentation assets
β”œβ”€β”€ pyproject.toml       # Project configuration
β”œβ”€β”€ setup.py            # Setup script
└── requirements.txt     # Core dependencies

Optional Dependencies

The project has several optional dependency groups:

  • ml: Machine Learning support (TensorFlow)

  • dev: Development tools (pytest, black, ruff, mypy)

  • examples: Jupyter notebooks support

  • docs: Documentation building tools

Install with:

pip install -e ".[ml,dev,examples]"  # Install specific groups
pip install -e ".[all]"              # Install all optional dependencies

Reporting Issues

When reporting issues, please include:

  • Python version

  • Operating system

  • Clear description of the problem

  • Minimal code example to reproduce

  • Expected vs actual behavior

Questions?

Feel free to open an issue for questions or reach out to the maintainers.

License

By contributing, you agree that your contributions will be licensed under the MIT License.