# Contributing to ContextGuard

Thank you for your interest in contributing! This document provides guidelines and instructions.

## Ways to Contribute

- **Bug reports**: Open an issue with reproduction steps
- **Feature requests**: Describe your idea and use case
- **Code contributions**: Fork, branch, commit, and send a PR
- **Documentation**: Improve README, docstrings, or examples
- **Security**: Report vulnerabilities via [SECURITY.md](SECURITY.md)

## Development Setup

```bash
git clone https://github.com/contextguard/contextguard.git
cd contextguard
pip install -e ".[dev,all]"   # Install with all optional features
pytest tests/                  # Run test suite
ruff check contextguard/       # Lint
```

## Code Standards

- **Python 3.9+** compatible
- **Type hints** for all public APIs
- **Docstrings** for classes and public methods (Google style)
- **Tests** for new features (minimum 80% coverage)
- **Linting**: `ruff check contextguard/` (line length: 100)

## Pull Request Process

1. Create a new branch: `git checkout -b feature/your-feature`
2. Make your changes and add tests
3. Run tests: `pytest tests/ -v`
4. Lint: `ruff check contextguard/`
5. Commit with clear message: `git commit -m "Add feature: ..."`
6. Push and open a PR with:
   - Description of changes
   - Motivation and context
   - Link to relevant issues
   - Test results (copy/paste from pytest output)

## Adding Detection Patterns

To add a new secret pattern:

```python
# In contextguard/secrets.py
_SECRET_PATTERNS.append((
    "my_new_secret",
    re.compile(r"my_pattern_regex"),
    0.9,  # severity weight 0-1
))
```

To add a custom pattern at runtime:

```python
from contextguard import Guard
guard = Guard(custom_secret_patterns=[
    ("my_pattern", r"regex_here", 0.8)
])
```

## Testing Guidelines

- Write tests in `tests/test_*.py`
- Use pytest fixtures for setup/teardown
- Aim for high coverage of critical paths (injection, secrets, PII)
- Include both positive and negative test cases

Example:

```python
def test_new_detection(detector):
    result = detector.detect("suspicious input")
    assert result.is_detected
    assert "pattern_label" in result.labels
```

## Documentation

- Keep README.md updated with API changes
- Update CHANGELOG.md when making releases
- Add docstrings to new functions
- Include usage examples in docstrings

## Release Process (Maintainers)

1. Update `version` in `pyproject.toml`
2. Update `CHANGELOG.md`
3. Create a git tag: `git tag v0.X.Y`
4. Push and create a GitHub Release
5. Build and upload: `python -m build && twine upload dist/*`

---

Questions? Open an issue or reach out to the maintainers. Happy contributing! 🚀
