Contributing
============

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

Getting Started
---------------

1. Fork the repository on GitHub
2. Clone your fork locally:

   .. code-block:: bash

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

3. Install development dependencies:

   .. code-block:: bash

      pip install -e ".[dev]"

4. Create a branch for your changes:

   .. code-block:: bash

      git checkout -b feature/your-feature-name

Development Setup
-----------------

Run Tests
~~~~~~~~~

.. code-block:: bash

   pytest tests/
   pytest tests/ -v --cov=specalign

Code Formatting
~~~~~~~~~~~~~~~

We use ``ruff`` for linting and formatting:

.. code-block:: bash

   ruff check src/
   ruff format src/

Type Checking
~~~~~~~~~~~~~

.. code-block:: bash

   mypy src/specalign

Build Documentation
~~~~~~~~~~~~~~~~~~~

.. code-block:: bash

   cd docs
   pip install -r requirements.txt
   sphinx-build -b html . _build/html

Contribution Guidelines
-----------------------

Code Style
~~~~~~~~~~

- Follow PEP 8 guidelines
- Use type hints for function signatures
- Write docstrings for public functions and classes
- Keep functions focused and single-purpose

Commit Messages
~~~~~~~~~~~~~~~

Use clear, descriptive commit messages:

.. code-block:: text

   Add feature: context pool diversity scoring

   - Implement MMR-based retrieval for diverse examples
   - Add diversity_weight configuration option
   - Update documentation with new feature

Pull Requests
~~~~~~~~~~~~~

1. Ensure all tests pass
2. Update documentation if needed
3. Add tests for new functionality
4. Keep PRs focused on a single change
5. Reference related issues in the PR description

Testing
~~~~~~~

- Write unit tests for new functionality
- Maintain test coverage above 80%
- Use pytest fixtures for common setup
- Test edge cases and error conditions

Areas for Contribution
----------------------

We especially welcome contributions in these areas:

- **New attack strategies**: Implement novel adversarial techniques
- **Provider integrations**: Add support for new API providers
- **Evaluation metrics**: New ways to measure attack/defense quality
- **Documentation**: Tutorials, examples, and guides
- **Bug fixes**: Help us squash bugs!

Reporting Issues
----------------

When reporting issues, please include:

1. SpecAlign version (``specalign --version``)
2. Python version
3. Operating system
4. Steps to reproduce
5. Expected vs actual behavior
6. Relevant logs or error messages

Code of Conduct
---------------

- Be respectful and inclusive
- Focus on constructive feedback
- Help others learn and grow
- Follow project maintainer decisions

Thank You!
----------

Thank you for contributing to SpecAlign! Your efforts help make AI systems safer and more aligned.