# Contributing to Burt Logger

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

## Development Setup

### 1. Clone the Repository

```bash
git clone https://github.com/yourusername/burt-logger-python.git
cd burt-logger-python
```

### 2. Create a Virtual Environment

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

# Or using conda
conda create -n burt-logger python=3.9
conda activate burt-logger
```

### 3. Install Development Dependencies

```bash
# Install package in editable mode with dev dependencies
pip install -e ".[dev]"

# Or use requirements-dev.txt
pip install -r requirements-dev.txt
```

### 4. Verify Installation

```bash
python verify_install.py
```

## Development Workflow

### Running Tests

```bash
# Run all tests
pytest

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

# Run specific test file
pytest tests/test_logger.py

# Run specific test
pytest tests/test_logger.py::TestLLMLoggerBasics::test_initialization

# Run with verbose output
pytest -v

# Run and stop at first failure
pytest -x
```

### Code Formatting

We use `black` for code formatting:

```bash
# Format all code
black burt_logger/ tests/ examples/

# Check formatting without making changes
black --check burt_logger/ tests/ examples/
```

### Linting

We use `flake8` for linting:

```bash
# Run flake8
flake8 burt_logger/ tests/ examples/

# With specific config
flake8 --max-line-length=100 --ignore=E203,W503 burt_logger/
```

### Type Checking

We use `mypy` for type checking:

```bash
# Run mypy
mypy burt_logger/

# With stricter checks
mypy --strict burt_logger/
```

### Import Sorting

We use `isort` for import sorting:

```bash
# Sort imports
isort burt_logger/ tests/ examples/

# Check without making changes
isort --check-only burt_logger/ tests/ examples/
```

### All Quality Checks at Once

```bash
# Run all quality checks
black --check burt_logger/ tests/ examples/ && \
flake8 burt_logger/ tests/ examples/ && \
isort --check-only burt_logger/ tests/ examples/ && \
mypy burt_logger/ && \
pytest --cov=burt_logger
```

## Contributing Guidelines

### Reporting Issues

When reporting issues, please include:

1. **Environment details:**

   -  Python version
   -  Operating system
   -  Package version

2. **Reproduction steps:**

   -  Minimal code to reproduce the issue
   -  Expected behavior
   -  Actual behavior

3. **Error messages:**
   -  Full stack trace
   -  Any relevant log output

### Submitting Pull Requests

1. **Fork the repository** and create a new branch:

   ```bash
   git checkout -b feature/your-feature-name
   ```

2. **Make your changes:**

   -  Write clear, readable code
   -  Follow existing code style
   -  Add docstrings to functions/classes
   -  Keep changes focused and atomic

3. **Add tests:**

   -  Write tests for new features
   -  Ensure existing tests pass
   -  Aim for high test coverage (>80%)

4. **Update documentation:**

   -  Update README.md if needed
   -  Add docstrings to new code
   -  Update CHANGELOG if applicable

5. **Run quality checks:**

   ```bash
   black burt_logger/ tests/
   flake8 burt_logger/ tests/
   pytest --cov=burt_logger
   ```

6. **Commit your changes:**

   ```bash
   git add .
   git commit -m "feat: add new feature description"
   ```

   Use conventional commit messages:

   -  `feat:` for new features
   -  `fix:` for bug fixes
   -  `docs:` for documentation
   -  `test:` for tests
   -  `refactor:` for refactoring
   -  `chore:` for maintenance

7. **Push and create pull request:**

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

   Then open a PR on GitHub with:

   -  Clear description of changes
   -  Link to related issues
   -  Screenshots if applicable

### Code Style Guidelines

1. **Python Style:**

   -  Follow PEP 8
   -  Use black for formatting (line length: 100)
   -  Use type hints where appropriate
   -  Write clear docstrings (Google style)

2. **Naming Conventions:**

   -  Classes: `PascalCase`
   -  Functions/methods: `snake_case`
   -  Constants: `UPPER_CASE`
   -  Private methods: `_leading_underscore`

3. **Docstring Format:**

   ```python
   def function_name(param1: str, param2: int) -> bool:
       """
       Brief description of what the function does.

       Args:
           param1 (str): Description of param1
           param2 (int): Description of param2

       Returns:
           bool: Description of return value

       Raises:
           ValueError: When something is wrong
       """
   ```

4. **Testing:**
   -  Use descriptive test names: `test_should_do_something_when_condition`
   -  One assertion per test when possible
   -  Use fixtures for common setup
   -  Mock external dependencies

### Adding New Features

When adding new features:

1. **Discuss first:**

   -  Open an issue to discuss the feature
   -  Get feedback from maintainers
   -  Ensure it aligns with project goals

2. **Keep it minimal:**

   -  Don't add unnecessary dependencies
   -  Keep the API simple
   -  Focus on the core use case

3. **Maintain backward compatibility:**

   -  Don't break existing APIs
   -  Add deprecation warnings if needed
   -  Update version appropriately

4. **Document thoroughly:**
   -  Add to README.md
   -  Include usage examples
   -  Update QUICKSTART.md if needed

### Project Structure

```
burt-logger-python/
├── burt_logger/          # Main package code
│   ├── __init__.py       # Package exports
│   └── logger.py         # Core logger implementation
├── tests/                # Test suite
│   ├── __init__.py
│   └── test_logger.py    # Logger tests
├── examples/             # Usage examples
│   ├── simple_example.py
│   ├── openai_example.py
│   └── anthropic_example.py
├── docs/                 # Documentation (future)
├── setup.py              # Package setup (legacy)
├── pyproject.toml        # Modern package config
├── requirements.txt      # Runtime dependencies
├── requirements-dev.txt  # Dev dependencies
├── README.md             # Main documentation
├── QUICKSTART.md         # Quick start guide
├── CONTRIBUTING.md       # This file
├── LICENSE               # MIT license
└── verify_install.py     # Installation verification
```

### Release Process

(For maintainers)

1. Update version in:

   -  `burt_logger/__init__.py`
   -  `setup.py`
   -  `pyproject.toml`

2. Update CHANGELOG.md

3. Create a git tag:

   ```bash
   git tag -a v0.1.0 -m "Release version 0.1.0"
   git push origin v0.1.0
   ```

4. Build and publish:
   ```bash
   python -m build
   python -m twine upload dist/*
   ```

## Getting Help

-  **Questions:** Open a GitHub discussion
-  **Bug reports:** Open a GitHub issue
-  **Security issues:** Email security@burt.ai
-  **General chat:** Join our Discord (coming soon)

## Code of Conduct

-  Be respectful and inclusive
-  Focus on constructive feedback
-  Help others learn and grow
-  Follow the Golden Rule

## License

By contributing, you agree that your contributions will be licensed under the MIT License.

---

Thank you for contributing to Burt Logger! 🎉
