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:

.. code-block:: bash

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

3. Install in development mode:

.. code-block:: bash

   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:

.. code-block:: bash

   # 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:

.. code-block:: bash

   # 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
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

.. code-block:: bash

   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:

.. code-block:: bash

   git checkout -b feature-name

2. Make your changes and add tests
3. Ensure all tests pass and code style checks pass
4. Commit your changes with a clear commit message
5. 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.