Contributing

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

Development Setup

Fork and clone the repository:

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

Create a virtual environment:

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

Install development dependencies:

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

Run tests:

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:

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:

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:

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

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

Docstring Format:

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

Create a new branch:

git checkout -b feature/my-feature

Make your changes and commit:

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

Run tests and linting:

pytest
flake8 django_agents
mypy django_agents

Push and create pull request:

git push origin feature/my-feature

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:

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:

feat(agents): Add async agent support

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

Fixes #42

fix(registry): Fix agent discovery race condition

Agent autodiscovery was failing when multiple apps
loaded simultaneously.

Adding New Features

When adding a new feature:

Open an issue to discuss the feature
Write tests first (TDD approach)
Implement the feature
Update documentation
Add example usage
Submit pull request

Example Feature Development:

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

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

Update version in __init__.py
Update CHANGELOG.md
Create release branch
Run full test suite
Build documentation
Create GitHub release
Publish to PyPI

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