Contributing to AmbiAlert¶

Thank you for your interest in contributing to AmbiAlert! This guide will help you get started.

Development Setup¶

Fork and clone the repository:

git clone https://github.com/yourusername/ambi-alert.git
cd ambi-alert

Create and activate a virtual environment:

uv venv
source .venv/bin/activate  # Linux/macOS
# or
.venv\Scripts\activate  # Windows

Install development dependencies:

uv pip install -e ".[dev]"

Install pre-commit hooks:
```
pre-commit install
```

Development Workflow¶

Create a new branch for your feature:

git checkout -b feature-name

Make your changes, following our coding standards:
Use type hints
Write docstrings for all public functions/methods
Follow PEP 8 style guidelines
Add tests for new functionality
Run tests:

pytest

Run linting and formatting:

ruff check .
ruff format .

Commit your changes:

git add .
git commit -m "Description of changes"

Push to your fork and create a pull request

Project Structure¶

ambi_alert/
├── __init__.py          # Package initialization
├── alerting.py          # Alert system implementation
├── cli.py              # Command-line interface
├── database.py         # Database management
├── main.py             # Main AmbiAlert class
├── monitor.py          # Website monitoring
└── query_expander.py   # Query expansion with AI

tests/
├── conftest.py         # Test configuration
├── test_alerting.py    # Alert system tests
├── test_database.py    # Database tests
├── test_main.py        # Main class tests
└── test_monitor.py     # Monitor tests

docs/                   # Documentation
├── index.md           # Home page
├── modules.md         # API reference
├── configuration.md   # Configuration guide
└── advanced.md        # Advanced usage guide

Testing¶

Running Tests¶

Run the full test suite:

pytest

Run with coverage:

pytest --cov=ambi_alert

Run specific test file:

pytest tests/test_monitor.py

Writing Tests¶

Place tests in the tests/ directory
Name test files test_*.py
Name test functions test_*
Use pytest fixtures for common setup
Use async tests for async functions
Mock external services

Example:

import pytest
from unittest.mock import AsyncMock, MagicMock

@pytest.mark.asyncio
async def test_feature():
    # Setup
    mock_service = AsyncMock()

    # Exercise
    result = await some_function(mock_service)

    # Verify
    assert result == expected_value
    mock_service.method.assert_called_once_with(args)

Documentation¶

Building Documentation¶

Build and serve documentation locally:

mkdocs serve

Build static site:

mkdocs build

Writing Documentation¶

Place documentation in docs/ directory
Use Markdown format
Include code examples
Update navigation in mkdocs.yml
Add docstrings to all public APIs

Code Style¶

We use ruff for linting and formatting:

# Check code
ruff check .

# Format code
ruff format .

Type Hints¶

Use type hints for all function arguments and return values:

from typing import Optional, List

def process_items(items: List[str], flag: Optional[bool] = None) -> dict[str, int]:
    """Process a list of items.

    Args:
        items: List of items to process
        flag: Optional processing flag

    Returns:
        Dictionary mapping items to counts
    """
    ...

Pull Request Process¶

Update documentation for new features
Add tests for new functionality
Ensure all tests pass
Update CHANGELOG.md
Request review from maintainers

Release Process¶

Update version in pyproject.toml
Update CHANGELOG.md
Create release commit:
```
git commit -m "Release v0.1.0"
```
Tag the release:
```
git tag v0.1.0
```
Push to GitHub:
```
git push origin main --tags
```

Getting Help¶

Open an issue for bugs
Start a discussion for questions
Join our community chat