# Contributing to openHealth

Thank you for your interest in contributing to openHealth! This document provides guidelines and information for contributors.

## Table of Contents

- [Code of Conduct](#code-of-conduct)
- [Getting Started](#getting-started)
- [Development Setup](#development-setup)
- [Contributing Guidelines](#contributing-guidelines)
- [Pull Request Process](#pull-request-process)
- [Testing](#testing)
- [Documentation](#documentation)
- [Release Process](#release-process)

## Code of Conduct

This project adheres to a [Code of Conduct](CODE_OF_CONDUCT.md). By participating, you are expected to uphold this code.

## Getting Started

### Prerequisites

- Python 3.7 or higher
- Git
- Basic knowledge of Python development
- Familiarity with health monitoring concepts (helpful but not required)

### Development Workflow

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests
5. Update documentation
6. Submit a pull request

## Development Setup

### 1. Clone Your Fork

```bash
git clone https://github.com/YOUR_USERNAME/openHealth.git
cd openHealth
```

### 2. Set Up Virtual Environment

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

### 3. Install Dependencies

```bash
# Install the package in development mode
pip install -e ".[dev]"

# This installs:
# - The package itself
# - Development dependencies (pytest, black, flake8, mypy, etc.)
# - Documentation dependencies (sphinx, etc.)
```

### 4. Verify Setup

```bash
# Run tests to ensure everything is working
pytest

# Run linting
black --check .
flake8 .

# Run type checking
mypy .
```

## Contributing Guidelines

### Code Style

We use several tools to maintain code quality:

- **Black**: Code formatting
- **Flake8**: Linting
- **MyPy**: Type checking
- **isort**: Import sorting

#### Pre-commit Hooks

We recommend using pre-commit hooks:

```bash
pre-commit install
```

This will run all quality checks before each commit.

### Code Standards

1. **Type Hints**: All new code should include type hints
2. **Documentation**: All public functions and classes must have docstrings
3. **Tests**: New features must include tests
4. **Error Handling**: Use appropriate exception handling with clear messages
5. **Logging**: Use the logging module for debug/info/error messages

### Documentation Standards

- Follow PEP 257 for docstrings
- Use Google-style docstrings
- Include type hints in function signatures
- Document all public APIs

Example:
```python
def check_service(
    url: str, 
    timeout: int = 30, 
    retries: int = 3
) -> HealthCheckResult:
    """Check the health of a service.
    
    Args:
        url: The URL of the service to check
        timeout: Request timeout in seconds
        retries: Number of retry attempts
        
    Returns:
        HealthCheckResult: The result of the health check
        
    Raises:
        ValueError: If URL is invalid
        TimeoutError: If request times out
    """
    pass
```

## Pull Request Process

### 1. Create a Branch

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

### 2. Make Changes

- Write clean, well-commented code
- Follow the coding standards above
- Add tests for new functionality
- Update documentation as needed

### 3. Commit Your Changes

Use conventional commit messages:

```
feat: add new feature
fix: fix bug in health check
docs: update installation guide
test: add tests for retry mechanism
refactor: improve notification system
```

### 4. 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 any relevant issues
- Include testing instructions
- Document any breaking changes

### Pull Request Template

```markdown
## Description
Brief description of changes

## Type of Change
- [ ] Bug fix
- [ ] New feature
- [ ] Breaking change
- [ ] Documentation update

## Testing
- [ ] Added tests for new functionality
- [ ] All tests pass
- [ ] Manual testing completed

## Checklist
- [ ] Code follows project style guidelines
- [ ] Self-review of code completed
- [ ] Documentation updated
- [ ] Changelog updated (if applicable)
```

## Testing

### Running Tests

```bash
# Run all tests
pytest

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

# Run specific test file
pytest tests/test_checker.py

# Run with verbose output
pytest -v
```

### Test Structure

- `tests/`: All test files
- `tests/test_*.py`: Unit tests for specific modules
- `tests/integration/`: Integration tests
- `tests/fixtures/`: Test data and configurations

### Writing Tests

1. **Unit Tests**: Test individual functions and classes
2. **Integration Tests**: Test component interaction
3. **Mock External Services**: Use pytest-mock for external dependencies
4. **Coverage**: Aim for high test coverage

Example test:
```python
def test_health_check_success(mock_session):
    """Test successful health check."""
    mock_response = Mock()
    mock_response.status_code = 200
    mock_response.json.return_value = {"status": "ok"}
    mock_session.get.return_value = mock_response
    
    checker = HealthChecker()
    result = checker.check_service("http://example.com")
    
    assert result.is_healthy()
    assert result.status_code == 200
```

## Documentation

### Types of Documentation

1. **API Documentation**: In-code docstrings
2. **User Documentation**: README, guides, tutorials
3. **Developer Documentation**: Contributing guide, architecture

### Building Documentation

```bash
cd docs/
make html
```

### Documentation Structure

- `README.md`: Overview and quick start
- `docs/`: Detailed documentation
- `examples/`: Usage examples
- `docs/api/`: API reference

## Release Process

### Version Management

We use Semantic Versioning (SemVer):
- `MAJOR.MINOR.PATCH`
- Breaking changes: increment MAJOR
- New features: increment MINOR
- Bug fixes: increment PATCH

### Release Checklist

1. Update version in `pyproject.toml`
2. Update version in `openHealth/__init__.py`
3. Update `CHANGELOG.md`
4. Tag the release
5. Build and publish to PyPI

### Building for Distribution

```bash
# Build source and wheel distributions
python -m build

# Check package
twine check dist/*

# Upload to Test PyPI
twine upload --repository testpypi dist/*

# Upload to PyPI (after testing)
twine upload dist/*
```

## Architecture Overview

### Core Components

- **Core**: Health checking logic, retry mechanisms
- **Notifications**: Email, Slack, webhook systems
- **Web**: Dashboard and API endpoints
- **CLI**: Command-line interface
- **Utils**: Logging, configuration, utilities

### Design Patterns

- **Strategy Pattern**: Different notification backends
- **Observer Pattern**: Status callbacks
- **Factory Pattern**: Configuration validators
- **Template Method**: Health check flow

## Getting Help

- **Issues**: Report bugs or request features
- **Discussions**: Ask questions or share ideas
- **Documentation**: Check existing docs first
- **Code Reviews**: Participate in reviewing PRs

## Recognition

Contributors will be recognized in:
- AUTHORS file
- Release notes
- README contributors section

Thank you for contributing to openHealth! 🎉

---

## Additional Resources

- [Python Packaging User Guide](https://packaging.python.org/)
- [pytest Documentation](https://docs.pytest.org/)
- [Black Code Formatter](https://black.readthedocs.io/)
- [MyPy Type Checking](https://mypy.readthedocs.io/)
- [PEP 8 Style Guide](https://www.python.org/dev/peps/pep-0008/)