# Contributing to augint-library

Thank you for your interest in contributing! This guide will help you get started quickly and ensure your contributions align with our standards.

## 🚀 Quick Start

```mermaid
graph LR
    A[Fork & Clone] --> B[Create Issue]
    B --> C[Create Branch]
    C --> D[Make Changes]
    D --> E[Run Tests]
    E --> F[Submit PR]
    F --> G[Auto Merge]

    style A fill:#e3f2fd
    style E fill:#fff3e0
    style G fill:#e8f5e9
```

## 📋 Contribution Process

### 1. Fork and Clone

```bash
# Fork on GitHub, then:
git clone https://github.com/YOUR_USERNAME/augint-library.git
cd augint-library
git remote add upstream https://github.com/Augmenting-Integrations/augint-library.git
```

### 2. Set Up Development Environment

```bash
# Install dependencies
uv sync --group security --group compliance

# Install pre-commit hooks
pre-commit install

# Verify setup
make test
```

### 3. Create an Issue First

Before starting work, create or find an issue describing what you want to do. This helps:
- Avoid duplicate work
- Get feedback on approach
- Track progress

### 4. Create a Feature Branch

```bash
# Update main
git checkout main
git pull upstream main

# Create branch with conventional naming
git checkout -b feat/issue-123-add-new-feature
# or: fix/issue-456-fix-bug
# or: docs/issue-789-update-readme
```

Branch naming convention:
- `feat/` - New features
- `fix/` - Bug fixes
- `docs/` - Documentation updates
- `test/` - Test additions/improvements
- `refactor/` - Code refactoring
- `chore/` - Maintenance tasks

### 5. Make Your Changes

Follow our coding standards:

```python
# ✅ Good: Clear function with type hints and docs
def process_data(items: list[dict], validate: bool = True) -> list[dict]:
    """Process a list of items with optional validation.

    Args:
        items: List of dictionaries to process
        validate: Whether to validate items before processing

    Returns:
        Processed items with added metadata

    Raises:
        ValidationError: If validation is enabled and items are invalid

    Example:
        >>> process_data([{"id": 1, "value": 10}])
        [{"id": 1, "value": 10, "processed": True}]
    """
    if validate:
        _validate_items(items)

    return [_process_item(item) for item in items]

# ❌ Bad: No types, no docs, unclear naming
def proc(d):
    return [{"processed": True, **x} for x in d]
```

### 6. Write Tests

We require 90%+ test coverage. Write tests FIRST (TDD):

```python
# tests/test_new_feature.py
import pytest
from mylib.feature import process_data
from mylib.exceptions import ValidationError

class TestProcessData:
    """Test the process_data function."""

    def test_process_valid_data(self):
        """Test processing valid data."""
        result = process_data([{"id": 1}])
        assert len(result) == 1
        assert result[0]["processed"] is True

    def test_validation_error(self):
        """Test validation error handling."""
        with pytest.raises(ValidationError) as exc_info:
            process_data([{"invalid": "data"}], validate=True)
        assert "Missing required field" in str(exc_info.value)

    def test_empty_list(self):
        """Test edge case of empty list."""
        assert process_data([]) == []
```

### 7. Run Quality Checks

Before committing, ensure all checks pass:

```bash
# Run all tests
make test-all

# Check code style
make lint
make format

# Type checking
make type-check

# Security scans
make security

# Or run everything at once
make pre-commit
```

### 8. Commit Your Changes

Use conventional commits:

```bash
# ✅ Good commits
git commit -m "feat: add data validation to process_data function"
git commit -m "fix: handle empty list in data processor"
git commit -m "docs: add examples to process_data docstring"
git commit -m "test: add edge cases for process_data"

# ❌ Bad commits
git commit -m "updated stuff"
git commit -m "fix"
git commit -m "WIP"
```

Commit format:
```
<type>(<scope>): <subject>

<body>

<footer>
```

Types:
- `feat`: New feature
- `fix`: Bug fix
- `docs`: Documentation only
- `style`: Code style (formatting, semicolons, etc)
- `refactor`: Code change that neither fixes a bug nor adds a feature
- `perf`: Performance improvement
- `test`: Adding missing tests
- `chore`: Changes to build process or auxiliary tools

### 9. Push and Create PR

```bash
git push -u origin feat/issue-123-add-new-feature
```

Then create a PR on GitHub. Your PR should:
- Reference the issue it closes: "Closes #123"
- Have a clear description
- Include any breaking changes
- Pass all CI checks

## 🔍 Code Review Process

```mermaid
graph TD
    A[PR Created] --> B{CI Passes?}
    B -->|No| C[Fix Issues]
    C --> B
    B -->|Yes| D{Code Review}
    D -->|Changes Requested| E[Address Feedback]
    E --> D
    D -->|Approved| F[Auto Merge]

    style B fill:#fff3e0
    style D fill:#f3e5f5
    style F fill:#e8f5e9
```

### What We Look For

1. **Code Quality**
   - Follows Python best practices
   - Has appropriate type hints
   - Includes comprehensive docstrings
   - No code duplication

2. **Testing**
   - 90%+ coverage for new code
   - Tests are clear and comprehensive
   - Edge cases are handled
   - Mocks are used appropriately

3. **Documentation**
   - API docs are updated
   - Examples are provided
   - README is updated if needed
   - CHANGELOG entry (auto-generated)

4. **Security**
   - No hardcoded secrets
   - Input validation
   - Safe file operations
   - Dependency versions pinned

## 🎯 Areas We Need Help

- **Documentation**: Improve examples, fix typos, add tutorials
- **Testing**: Increase coverage, add edge cases, improve fixtures
- **Performance**: Optimize slow operations, add benchmarks
- **Features**: Check issues labeled "help wanted" or "good first issue"
- **Security**: Report vulnerabilities, improve scanning rules

## 📚 Resources

- [Code of Conduct](CODE_OF_CONDUCT.md)
- [Development Guide](guides/development/README.md)
- [Architecture Decisions](guides/architecture/adr/)
- [API Documentation](https://svange.github.io/augint-library)

## 💬 Getting Help

- **Questions**: Open a discussion on GitHub
- **Bugs**: Create an issue with reproduction steps
- **Security**: Email security@example.com (do not open public issues)

## 🎉 Recognition

Contributors are recognized in:
- [CHANGELOG.md](CHANGELOG.md) - Auto-generated from commits
- [README.md](README.md) - Major contributors
- Release notes - All contributors for that release

Thank you for contributing to augint-library! 🚀
