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

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

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

1. Clone the repository::

    git clone https://github.com/genexus/pygeai-orchestration.git
    cd pygeai-orchestration

2. Create a virtual environment::

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

3. Install development dependencies::

    pip install -e ".[dev]"

4. Install pre-commit hooks::

    pre-commit install

Code Quality
------------

We use several tools to maintain code quality:

* **Ruff**: For linting and formatting
* **unittest**: For testing
* **MyPy**: For type checking (future)

Running Tests
~~~~~~~~~~~~~

Run all tests::

    python -m unittest discover pygeai_orchestration/tests/

Run with verbose output::

    python -m unittest discover pygeai_orchestration/tests/ -v

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

Format code with Ruff::

    ruff format pygeai_orchestration/

Check for issues::

    ruff check pygeai_orchestration/

Fix auto-fixable issues::

    ruff check pygeai_orchestration/ --fix

Guidelines
----------

Code Guidelines
~~~~~~~~~~~~~~~

1. Follow PEP 8 style guide
2. Add type hints to all functions
3. Write comprehensive docstrings (Google style)
4. Keep functions focused and small
5. Use meaningful variable names

Documentation Guidelines
~~~~~~~~~~~~~~~~~~~~~~~~

1. Document all public APIs
2. Include usage examples
3. Keep examples simple and clear
4. Update changelog for notable changes

Testing Guidelines
~~~~~~~~~~~~~~~~~~

1. Write tests for new features
2. Maintain or improve coverage
3. Test edge cases and error conditions
4. Use descriptive test names

Contribution Process
--------------------

1. Fork the repository
2. Create a feature branch::

    git checkout -b feature/your-feature-name

3. Make your changes
4. Add tests for new functionality
5. Ensure all tests pass
6. Update documentation
7. Commit with clear messages::

    git commit -m "Add feature: description"

8. Push to your fork::

    git push origin feature/your-feature-name

9. Open a Pull Request

Pull Request Checklist
----------------------

Before submitting a PR, ensure:

- [ ] Code follows style guidelines
- [ ] All tests pass
- [ ] New tests added for new features
- [ ] Documentation updated
- [ ] Changelog updated
- [ ] Type hints added
- [ ] No linting errors

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

When reporting issues, include:

* Python version
* PyGEAI Orchestration version
* Minimal reproducible example
* Expected vs actual behavior
* Error messages and stack traces

Feature Requests
----------------

For feature requests, describe:

* Use case and motivation
* Proposed API or interface
* Alternative solutions considered
* Potential implementation approach

License
-------

By contributing, you agree that your contributions will be licensed under the same license as the project.

Questions?
----------

* Open an issue for questions
* Join our community discussions
* Check existing issues and PRs

Thank you for contributing to PyGEAI Orchestration!
