Contributing#

Thank you for your interest in contributing to Hyperactive! This guide will help you get started with development and submit your contributions.

How to Contribute#

Contribution Workflow#

Fork the repository on GitHub
Clone your fork locally
Create a branch for your changes
Make your changes with tests
Run the test suite to ensure everything works
Submit a pull request for review

Types of Contributions#

We welcome many types of contributions:

Bug fixes: Fix issues and improve stability
New features: Add new optimizers, experiments, or integrations
Documentation: Improve guides, examples, and API docs
Tests: Increase test coverage
Performance: Optimize code for speed or memory

Development Setup#

Prerequisites#

Python 3.10 or higher
Git
pip

Setting Up Your Environment#

Fork and clone the repository:

git clone https://github.com/YOUR-USERNAME/Hyperactive.git
cd Hyperactive

Create a virtual environment:

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

Install in development mode with test dependencies:
```
pip install -e ".[test,docs]"
```

Verify the installation:

python -c "import hyperactive; print(hyperactive.__version__)"

Running Tests#

Run the test suite to ensure everything works:

# Run all tests
pytest

# Run with coverage report
pytest --cov=hyperactive

# Run specific test file
pytest tests/test_specific.py

# Run tests matching a pattern
pytest -k "test_hill_climbing"

Code Style#

Formatting#

Hyperactive uses Black for code formatting and Ruff for linting:

# Format code
black src/hyperactive tests

# Check linting
ruff check src/hyperactive tests

# Auto-fix linting issues
ruff check --fix src/hyperactive tests

Docstrings#

Use NumPy-style docstrings for all public functions and classes:

def my_function(param1, param2):
    """Short description of the function.

    Longer description if needed.

    Parameters
    ----------
    param1 : type
        Description of param1.
    param2 : type
        Description of param2.

    Returns
    -------
    type
        Description of return value.

    Examples
    --------
    >>> my_function(1, 2)
    3
    """
    return param1 + param2

Type Hints#

Add type hints to function signatures:

def optimize(
    self,
    search_space: dict,
    n_iter: int,
    experiment: Callable,
) -> dict:
    ...

Submitting Changes#

Creating a Pull Request#

Create a branch for your changes:
```
git checkout -b feature/my-new-feature
```

Make your changes and commit:

git add .
git commit -m "Add my new feature"

Push to your fork:
```
git push origin feature/my-new-feature
```
Open a pull request on GitHub from your branch to the main repository.

Pull Request Guidelines#

Clear title: Describe what the PR does
Description: Explain the changes and motivation
Tests: Include tests for new functionality
Documentation: Update docs if needed
Small scope: Keep PRs focused on one thing

Commit Messages#

Write clear, descriptive commit messages:

Add Bayesian optimizer warm start support

- Add warm_start parameter to BayesianOptimizer
- Update documentation with usage examples
- Add tests for warm start functionality

Review Process#

What to Expect#

Automated checks: CI will run tests and linting
Code review: Maintainers will review your code
Feedback: You may be asked to make changes
Merge: Once approved, your PR will be merged

Response Time#

Maintainers are volunteers, so response times may vary. We aim to:

Acknowledge PRs within a few days
Provide initial review within a week
Merge approved PRs promptly

Getting Help#

If you need help:

Check existing issues and discussions
Ask on Discord
Tag @SimonBlanke in your PR for attention

Thank you for contributing to Hyperactive!