Contributing

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

Development Setup

  1. Fork and clone the repository:

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

  2. Set up development environment:

    # Using uv (recommended)
uv sync --dev

# Or using pip
pip install -e ".[dev]"

  3. Install pre-commit hooks:

    pre-commit install

Code Style

We follow standard Python coding conventions:

  • PEP 8 for code style

  • Black for code formatting

  • isort for import sorting

  • flake8 for linting

Run code formatting:

black .
isort .
flake8 .

Testing

We use pytest for testing. Run the test suite:

# Run all tests
pytest

# Run with coverage
pytest --cov=openeobench

# Run specific test file
pytest tests/test_service_checking.py

Writing Tests

When adding new features, please include tests:

import pytest
from openeobench import service_checker

def test_service_check():
    """Test service availability checking."""
    result = service_checker.check_endpoint("https://example.com")
    assert result is not None
    assert "response_time" in result

Adding New Features

  1. Create a feature branch:

    git checkout -b feature/your-feature-name

  2. Implement your feature:

    • Add the functionality to the appropriate module

    • Include comprehensive docstrings

    • Add command-line interface if applicable

    • Include error handling

  3. Add tests:

    • Unit tests for individual functions

    • Integration tests for complete workflows

    • Test edge cases and error conditions

  4. Update documentation:

    • Add docstrings to all new functions/classes

    • Update relevant .rst files in docs/source/

    • Add usage examples if appropriate

  5. Submit a pull request:

    • Describe the feature and its benefits

    • Include test results

    • Reference any related issues

Documentation

Documentation is built using Sphinx. To build locally:

cd docs
make html

The documentation will be available in docs/build/html/.

Documentation Guidelines

  • Use clear, concise language

  • Include code examples for all features

  • Document all parameters and return values

  • Add cross-references between related sections

Release Process

  1. Update version in pyproject.toml

  2. Update changelog with new features and fixes

  3. Create release tag:

    git tag -a v1.0.0 -m "Release version 1.0.0"
git push origin v1.0.0

  4. Build and publish:

    uv build
uv publish

Bug Reports

When reporting bugs, please include:

  • Environment details (OS, Python version, dependency versions)

  • Minimal reproduction example

  • Expected vs actual behavior

  • Error messages and stack traces

  • Relevant configuration files

Feature Requests

For new feature requests:

  • Describe the use case and problem to solve

  • Propose a solution or approach

  • Consider backwards compatibility

  • Provide examples of how it would be used

Code of Conduct

We are committed to providing a welcoming and inclusive environment for all contributors. Please:

  • Be respectful and professional

  • Welcome newcomers and help them get started

  • Focus on constructive feedback

  • Respect different viewpoints and experiences

Getting Help

If you need help:

  • Check the documentation first

  • Search existing issues on GitHub

  • Ask questions in GitHub discussions

  • Join our community channels (if available)

Development Workflow

  1. Check existing issues to avoid duplicate work

  2. Create an issue for significant changes

  3. Fork the repository and create a feature branch

  4. Make your changes with tests and documentation

  5. Run the test suite and ensure all tests pass

  6. Submit a pull request with a clear description

  7. Address review feedback promptly

  8. Celebrate when your contribution is merged! 🎉

Thank you for contributing to openEObench!