# Contributing to {{ project_name }}

Thank you for your interest in contributing to {{ project_name }}! This document provides guidelines and instructions for contributing.

## Code of Conduct

This project follows a Code of Conduct that all contributors are expected to adhere to. Please be respectful and constructive in all interactions.

## Getting Started

### Prerequisites

- Python {{ python_version }}+
- [uv](https://github.com/astral-sh/uv) package manager
- Git

### Development Setup

1. **Fork and clone the repository**

```bash
git clone https://github.com/{{ author_name }}/{{ project_slug }}.git
cd {{ project_slug }}
```

2. **Install dependencies**

```bash
uv sync --all-extras
```

3. **Install pre-commit hooks**

```bash
uv run pre-commit install
```

4. **Run tests to verify setup**

```bash
uv run pytest
```

## Development Workflow

### 1. Create a Branch

```bash
git checkout -b feature/your-feature-name
# or
git checkout -b fix/your-bug-fix
```

Branch naming conventions:
- `feature/` - New features
- `fix/` - Bug fixes
- `docs/` - Documentation updates
- `refactor/` - Code refactoring
- `test/` - Test additions or updates

### 2. Make Changes

- Write clean, readable code
- Follow the existing code style
- Add tests for new functionality
- Update documentation as needed

### 3. Run Tests and Linting

```bash
# Run all checks
make all

# Or individually:
make lint      # Check code style
make format    # Format code
make typecheck # Type checking
make test      # Run tests
```

### 4. Commit Changes

We follow [Conventional Commits](https://www.conventionalcommits.org/):

```bash
# Format: <type>(<scope>): <subject>

git commit -m "feat(tools): add new data processing tool"
git commit -m "fix(server): resolve connection timeout issue"
git commit -m "docs(readme): update installation instructions"
```

Types:
- `feat`: New feature
- `fix`: Bug fix
- `docs`: Documentation changes
- `style`: Code style changes (formatting, etc.)
- `refactor`: Code refactoring
- `test`: Test changes
- `chore`: Build process or auxiliary tool changes

### 5. Push and Create Pull Request

```bash
git push origin feature/your-feature-name
```

Then create a Pull Request on GitHub with:
- Clear title and description
- Reference to related issues
- Screenshots (if UI changes)
- Test results

## Code Style

### Python Style Guide

We follow PEP 8 with some modifications:
- Line length: 100 characters
- Use `ruff` for linting and formatting
- Type hints required for public APIs

### Type Hints

```python
def process_data(input: str, timeout: int = 30) -> dict[str, Any]:
    """Process input data with timeout."""
    ...
```

### Docstrings

Use Google-style docstrings:

```python
def complex_function(param1: str, param2: int) -> bool:
    """
    Brief description of what the function does.
    
    Longer description if needed, explaining the purpose,
    behavior, and any important details.
    
    Args:
        param1: Description of param1
        param2: Description of param2
        
    Returns:
        Description of return value
        
    Raises:
        ValueError: When param1 is empty
        
    Example:
        >>> complex_function("test", 42)
        True
    """
    ...
```

## Testing

### Writing Tests

- Place tests in the `tests/` directory
- Use pytest fixtures for setup
- Aim for >80% code coverage
- Test edge cases and error conditions

```python
import pytest
from {{ package_name }}.module import function

def test_function_success():
    """Test successful execution."""
    result = function("valid_input")
    assert result == expected_value

def test_function_error():
    """Test error handling."""
    with pytest.raises(ValueError):
        function("invalid_input")

@pytest.mark.asyncio
async def test_async_function():
    """Test async function."""
    result = await async_function()
    assert result is not None
```

### Running Tests

```bash
# All tests
uv run pytest

# Specific test file
uv run pytest tests/test_module.py

# Specific test
uv run pytest tests/test_module.py::test_function

# With coverage
uv run pytest --cov={{ package_name }} --cov-report=html

# Watch mode
uv run ptw
```

## Documentation

### Updating Documentation

- Keep README.md up to date
- Update docstrings for code changes
- Add usage examples for new features
- Update API documentation

### Building Documentation

```bash
# If using mkdocs
uv run mkdocs serve
```

## Pull Request Process

1. **Before Submitting**
   - Run all tests and ensure they pass
   - Run linting and type checking
   - Update documentation
   - Rebase on latest main branch

2. **PR Description Should Include**
   - What changes were made
   - Why the changes were necessary
   - How to test the changes
   - Any breaking changes
   - Related issue numbers

3. **Review Process**
   - At least one approval required
   - All checks must pass
   - Address review feedback
   - Keep PR focused and reasonably sized

4. **After Approval**
   - Squash commits if requested
   - Maintain clean commit history

## Issue Reporting

### Bug Reports

Include:
- Clear, descriptive title
- Steps to reproduce
- Expected vs actual behavior
- Environment details (OS, Python version)
- Error messages and logs
- Minimal reproducible example

### Feature Requests

Include:
- Clear description of the feature
- Use cases and benefits
- Possible implementation approach
- Any breaking changes

## Release Process

Releases are managed by maintainers:
1. Version bump in `pyproject.toml`
2. Update CHANGELOG.md
3. Create git tag
4. GitHub Actions handles publishing

## Questions?

- Open an issue for discussion
- Join our community chat (if applicable)
- Email: {{ author_email }}

## License

By contributing, you agree that your contributions will be licensed under the {{ license_type | upper }} License.

---

Thank you for contributing to {{ project_name }}! 🎉