# Contributing to Django Security Suite

Thank you for your interest in contributing to Django Security Suite! We welcome contributions from the community and are grateful for any help you can provide.

## Table of Contents

- [Code of Conduct](#code-of-conduct)
- [Getting Started](#getting-started)
- [How to Contribute](#how-to-contribute)
- [Development Setup](#development-setup)
- [Testing](#testing)
- [Submitting Changes](#submitting-changes)
- [Style Guidelines](#style-guidelines)
- [Security Issues](#security-issues)
- [Documentation](#documentation)
- [Community](#community)

## Code of Conduct

This project adheres to a Code of Conduct. By participating, you are expected to uphold this code. Please report unacceptable behavior to security@django-security-suite.org.

## Getting Started

1. Fork the repository on GitHub
2. Clone your fork locally
3. Create a new branch for your feature or bugfix
4. Make your changes
5. Submit a pull request

## How to Contribute

### Reporting Bugs

Before creating bug reports, please check existing issues to avoid duplicates. When you create a bug report, include:

- A clear and descriptive title
- Steps to reproduce the issue
- Expected behavior
- Actual behavior
- Your environment (OS, Python version, Django version)
- Any relevant logs or error messages

### Suggesting Enhancements

Enhancement suggestions are tracked as GitHub issues. When creating an enhancement suggestion, include:

- A clear and descriptive title
- A detailed description of the proposed enhancement
- Any possible drawbacks or considerations
- Examples of how the enhancement would be used

### Pull Requests

1. Follow the style guidelines
2. Include tests for new functionality
3. Update documentation as needed
4. Ensure all tests pass
5. Add a changelog entry if applicable

## Development Setup

### Prerequisites

- Python 3.10 or higher
- Git
- Redis (for testing rate limiting)
- PostgreSQL (optional, for testing database features)

### Installation

```bash
# Clone your fork
git clone https://github.com/YOUR-USERNAME/django-security-suite.git
cd django-security-suite

# Create a virtual environment
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Install in development mode
pip install -e ".[dev,test,docs]"

# Install pre-commit hooks
pre-commit install
```

### Running the Development Server

```bash
# Run the example project
cd examples/basic_setup
python manage.py migrate
python manage.py runserver
```

## Testing

### Running Tests

```bash
# Run all tests
pytest

# Run with coverage
pytest --cov=django_security_suite --cov-report=html

# Run specific test file
pytest tests/test_authentication.py

# Run tests for specific Django version
tox -e py311-django42
```

### Writing Tests

- Place tests in the `tests/` directory
- Follow the naming convention `test_*.py`
- Use pytest fixtures for common setup
- Include both unit and integration tests
- Test edge cases and error conditions

Example test:

```python
import pytest
from django.test import TestCase
from django_security_suite.authentication.validators import ComplexityValidator

class TestPasswordValidators(TestCase):
    def test_complexity_validator_requires_uppercase(self):
        validator = ComplexityValidator()

        with pytest.raises(ValidationError):
            validator.validate('nocapitals123!')

        # Should not raise
        validator.validate('HasCapitals123!')
```

## Submitting Changes

### Commit Messages

Follow the conventional commits specification:

- `feat:` New feature
- `fix:` Bug fix
- `docs:` Documentation changes
- `test:` Test additions or changes
- `refactor:` Code refactoring
- `perf:` Performance improvements
- `chore:` Maintenance tasks
- `security:` Security improvements

Example:
```
feat: add rate limiting for password reset endpoint

- Implement sliding window rate limiting
- Add configuration options for limits
- Include tests and documentation
```

### Pull Request Process

1. Create a pull request against the `develop` branch
2. Fill out the pull request template
3. Ensure all CI checks pass
4. Wait for code review
5. Address any feedback
6. Once approved, the PR will be merged

## Style Guidelines

### Python Code Style

We use Black for code formatting and Ruff for linting:

```bash
# Format code
black django_security_suite tests

# Check linting
ruff check django_security_suite tests

# Type checking
mypy django_security_suite
```

### Code Style Rules

- Line length: 120 characters
- Use type hints for function signatures
- Include docstrings for all public functions and classes
- Follow PEP 8 naming conventions
- Use f-strings for string formatting
- Prefer pathlib over os.path

### Documentation Style

- Use Google-style docstrings
- Include examples in docstrings where helpful
- Keep README examples up to date
- Document all configuration options

Example docstring:

```python
def rate_limit(limit: str, key: str = 'ip') -> Callable:
    """
    Decorator to apply rate limiting to a view.

    Args:
        limit: Rate limit string (e.g., '10/m' for 10 per minute)
        key: Key to use for rate limiting ('ip', 'user', or callable)

    Returns:
        Decorated view function

    Example:
        @rate_limit('5/m', key='user')
        def my_view(request):
            return HttpResponse('Hello')

    Raises:
        RateLimitExceeded: When rate limit is exceeded
    """
```

## Security Issues

### Reporting Security Vulnerabilities

**DO NOT** create public GitHub issues for security vulnerabilities. Instead:

1. Email security@django-security-suite.org
2. Include:
   - Description of the vulnerability
   - Steps to reproduce
   - Potential impact
   - Any suggested fixes

We will respond within 48 hours and work with you to address the issue.

## Documentation

### Building Documentation

```bash
# Install documentation dependencies
pip install -e ".[docs]"

# Build documentation
mkdocs build

# Serve documentation locally
mkdocs serve
```

### Documentation Guidelines

- Keep examples simple and focused
- Include both basic and advanced usage
- Document all public APIs
- Maintain changelog for all releases
- Update migration guides for breaking changes

## Community

### Getting Help

- GitHub Issues: For bugs and feature requests
- GitHub Discussions: For questions and general discussion
- Stack Overflow: Tag questions with `django-security-suite`

### Contributing Translations

We welcome translations! Please see the `locale/` directory for existing translations and follow Django's i18n guidelines.

### Code Reviews

All submissions require review. We use GitHub pull requests for this purpose. Consult [GitHub Help](https://help.github.com/articles/about-pull-requests/) for more information.

## Recognition

Contributors who submit accepted pull requests will be added to the AUTHORS file and acknowledged in release notes.

## License

By contributing to Django Security Suite, you agree that your contributions will be licensed under the MIT License.

---

Thank you for contributing to Django Security Suite! Your efforts help make Django applications more secure for everyone.