Contributing

We welcome contributions to the BiSC algorithm package! This document outlines how to contribute to the project.

Development Setup

  1. Fork the repository on GitHub

  2. Clone your fork locally:

git clone https://github.com/AcraeaTerpsicore/bisc-python.git
cd bisc-python

  1. Install in development mode:

pip install -e ".[dev]"

This installs the package in editable mode with development dependencies.

Code Style

We use several tools to maintain code quality:

  • Black for code formatting

  • Flake8 for linting

  • MyPy for type checking

Run these tools before submitting:

# Format code
black bisc_package/

# Check linting
flake8 bisc_package/

# Type checking
mypy bisc_package/

Testing

We use pytest for testing. Run the test suite:

# Run all tests
pytest

# Run with coverage
pytest --cov=bisc_package

# Run specific test categories
pytest -m unit        # Unit tests only
pytest -m integration # Integration tests only

Writing Tests

  • Write unit tests for individual functions and classes

  • Write integration tests for algorithm workflows

  • Place tests in appropriate directories under bisc_package/tests/

  • Use descriptive test names and docstrings

Documentation

Documentation is built with Sphinx and hosted on Read the Docs.

Building Documentation Locally

cd docs/
pip install -r requirements.txt
make html

The documentation will be built in docs/_build/html/.

Documentation Style

  • Write clear, concise docstrings for all public functions and classes

  • Use Google-style docstrings

  • Include examples in docstrings where helpful

  • Update the documentation when adding new features

Submitting Changes

  1. Create a new branch for your feature:

git checkout -b feature-name

  1. Make your changes and add tests

  2. Ensure all tests pass and code style checks pass

  3. Commit your changes with a clear commit message

  4. Push to your fork and submit a pull request

Pull Request Guidelines

  • Include a clear description of the changes

  • Reference any related issues

  • Ensure all tests pass

  • Update documentation if necessary

  • Keep pull requests focused on a single feature or bug fix

Reporting Issues

  • Use the GitHub issue tracker

  • Provide a clear description of the problem

  • Include steps to reproduce the issue

  • Include relevant code examples

  • Specify your Python version and operating system

Feature Requests

  • Use the GitHub issue tracker with the “enhancement” label

  • Describe the desired functionality clearly

  • Explain the use case and why it would be beneficial

  • Consider whether it fits within the scope of the project

Code Review Process

All submissions go through code review:

  1. A maintainer will review your pull request

  2. Feedback will be provided if changes are needed

  3. Once approved, the pull request will be merged

  4. The feature will be included in the next release

Release Process

Releases follow semantic versioning:

  • Major (X.0.0): Breaking changes

  • Minor (0.X.0): New features, backward compatible

  • Patch (0.0.X): Bug fixes, backward compatible

Getting Help

  • Check the documentation first

  • Search existing issues on GitHub

  • Ask questions in GitHub Discussions

  • Contact the maintainers if needed

Community Guidelines

  • Be respectful and inclusive

  • Follow the Python Community Code of Conduct

  • Help others learn and grow

  • Give constructive feedback

Thank You

Thank you for contributing to the BiSC algorithm package! Your contributions help make this tool better for the entire combinatorics research community.