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

We welcome contributions to django-agents! This guide will help you get started.

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

1. Fork and clone the repository:

.. code-block:: bash

    git clone https://github.com/dim-gggl/django_agents.git
    cd django_agents

2. Create a virtual environment:

.. code-block:: bash

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

3. Install development dependencies:

.. code-block:: bash

    pip install -r requirements-dev.txt
    pip install -e .

4. Run tests:

.. code-block:: bash

    pytest

Code Style
----------

We follow PEP 8 style guidelines with these specifics:

* Maximum line length: 100 characters
* Use type hints for all functions and methods
* Write docstrings in Google/NumPy style for Sphinx
* Use f-strings for string formatting

Example:

.. code-block:: python

    def my_function(param: str, option: int = 0) -> Dict[str, Any]:
        """
        Brief description of the function.

        Longer description if needed, explaining the purpose and behavior.

        Args:
            param (str): Description of param.
            option (int, optional): Description of option. Defaults to 0.

        Returns:
            Dict[str, Any]: Description of return value.

        Raises:
            ValueError: When param is invalid.

        Example:
            >>> result = my_function("test")
            >>> print(result)
            {'success': True}
        """
        pass

Writing Tests
-------------

All new features must include tests. We use pytest with Django integration.

Test Structure:

.. code-block:: python

    from django.test import TestCase
    from myapp.agents import MyAgent

    class MyAgentTest(TestCase):
        """Test suite for MyAgent."""

        def setUp(self):
            """Set up test fixtures."""
            self.agent = MyAgent()

        def test_agent_execution(self):
            """Test basic agent execution."""
            result = self.agent.run({'test': 'data'})
            self.assertTrue(result['success'])

        def test_context_validation(self):
            """Test context validation."""
            with self.assertRaises(AgentValidationError):
                self.agent.run({})

Run tests:

.. code-block:: bash

    # All tests
    pytest

    # Specific test file
    pytest tests/test_agents.py

    # With coverage
    pytest --cov=django_agents

Documentation
-------------

All code must be documented using Google-style docstrings for Sphinx.

Build Documentation:

.. code-block:: bash

    cd docs
    make html
    open _build/html/index.html

Docstring Format:

.. code-block:: python

    class MyAgent(BaseAgent):
        """
        Brief one-line description.

        Longer detailed description explaining the agent's purpose,
        behavior, and usage patterns.

        Attributes:
            name (str): Agent name.
            description (str): Agent description.

        Example:
            >>> agent = MyAgent()
            >>> result = agent.run({'key': 'value'})
        """

        def execute(self, context: Dict[str, Any]) -> Dict[str, Any]:
            """
            Execute the agent logic.

            Args:
                context: Execution context with parameters.

            Returns:
                Execution result dictionary.

            Raises:
                AgentExecutionError: If execution fails.
            """
            pass

Pull Request Process
--------------------

1. Create a new branch:

.. code-block:: bash

    git checkout -b feature/my-feature

2. Make your changes and commit:

.. code-block:: bash

    git add .
    git commit -m "Add feature: description"

3. Run tests and linting:

.. code-block:: bash

    pytest
    flake8 django_agents
    mypy django_agents

4. Push and create pull request:

.. code-block:: bash

    git push origin feature/my-feature

5. PR Requirements:

   * All tests pass
   * Code coverage maintained or improved
   * Documentation updated
   * CHANGELOG.md updated
   * Follows code style guidelines

Commit Message Guidelines
-------------------------

Follow conventional commits format:

.. code-block:: text

    type(scope): Brief description

    Longer explanation if needed

    Fixes #123

Types:

* ``feat``: New feature
* ``fix``: Bug fix
* ``docs``: Documentation changes
* ``style``: Code style changes (formatting)
* ``refactor``: Code refactoring
* ``test``: Test additions or changes
* ``chore``: Maintenance tasks

Examples:

.. code-block:: text

    feat(agents): Add async agent support

    Added AsyncAgent base class with queue support and
    asynchronous execution capabilities.

    Fixes #42

.. code-block:: text

    fix(registry): Fix agent discovery race condition

    Agent autodiscovery was failing when multiple apps
    loaded simultaneously.

Adding New Features
-------------------

When adding a new feature:

1. Open an issue to discuss the feature
2. Write tests first (TDD approach)
3. Implement the feature
4. Update documentation
5. Add example usage
6. Submit pull request

Example Feature Development:

.. code-block:: bash

    # 1. Create branch
    git checkout -b feature/workflow-retry

    # 2. Write test
    # tests/test_workflow.py

    # 3. Implement feature
    # django_agents/workflow.py

    # 4. Update docs
    # docs/api/workflow.rst

    # 5. Test and commit
    pytest
    git commit -am "feat(workflow): Add retry mechanism"

Bug Reports
-----------

When reporting bugs, include:

* Django version
* django-agents version
* Python version
* Minimal reproduction example
* Expected vs actual behavior
* Stack trace if applicable

Use this template:

.. code-block:: text

    **Describe the bug**
    Clear description of the bug.

    **To Reproduce**
    Steps to reproduce:
    1. Create agent...
    2. Execute with...
    3. See error

    **Expected behavior**
    What should happen.

    **Environment:**
    - Django: 4.2
    - django-agents: 0.1.0
    - Python: 3.9

    **Stack trace**
    ```python
    Traceback...
    ```

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

For feature requests:

* Explain the use case
* Describe the proposed solution
* Consider alternative approaches
* Discuss impact on existing features

Release Process
---------------

Maintainers follow this process:

1. Update version in ``__init__.py``
2. Update CHANGELOG.md
3. Create release branch
4. Run full test suite
5. Build documentation
6. Create GitHub release
7. Publish to PyPI

.. code-block:: bash

    # Update version
    # django_agents/__init__.py: __version__ = "0.2.0"

    # Build and test
    python setup.py sdist bdist_wheel
    twine check dist/*

    # Upload to test PyPI
    twine upload --repository-url https://test.pypi.org/legacy/ dist/*

    # Upload to PyPI
    twine upload dist/*

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

We follow the Django Code of Conduct. Be respectful, inclusive, and professional.

Getting Help
------------

* Documentation: https://django-agents.readthedocs.io
* Issues: https://github.com/yourusername/django-agents/issues
* Discussions: https://github.com/yourusername/django-agents/discussions

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

Thank you for contributing to django-agents! Your efforts help make this project better for everyone.