# Contributing to OCLAWMA

Thank you for your interest in contributing to OCLAWMA! This document provides guidelines for contributing.

## Table of Contents

- [Code of Conduct](#code-of-conduct)
- [Getting Started](#getting-started)
- [Development Setup](#development-setup)
- [Making Changes](#making-changes)
- [Testing](#testing)
- [Code Style](#code-style)
- [Commit Messages](#commit-messages)
- [Pull Requests](#pull-requests)
- [Documentation](#documentation)
- [Release Process](#release-process)

## Code of Conduct

This project adheres to a code of conduct. By participating, you are expected to uphold this code:

- Be respectful and inclusive
- Welcome newcomers
- Focus on constructive feedback
- Respect different viewpoints

## Getting Started

1. Fork the repository
2. Clone your fork: `git clone https://github.com/YOUR_USERNAME/oclawma.git`
3. Create a branch: `git checkout -b feature/my-feature`

## Development Setup

```bash
# Clone your fork
git clone https://github.com/YOUR_USERNAME/oclawma.git
cd oclawma

# Create virtual environment
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Install in development mode
pip install -e ".[dev]"

# Verify installation
pytest --version
black --version
ruff --version
mypy --version
```

## Making Changes

1. **Create a branch** from `main`:
   ```bash
   git checkout -b feature/my-feature
   ```

2. **Make your changes** with clear, focused commits

3. **Test your changes**:
   ```bash
   pytest
   ```

4. **Format and lint**:
   ```bash
   black src tests
   ruff check src tests
   mypy src
   ```

## Testing

Run the full test suite:

```bash
# Run all tests
pytest

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

# Run specific test file
pytest tests/test_skills.py

# Run with verbose output
pytest -v

# Run failing tests only
pytest --lf
```

### Writing Tests

- Place tests in `tests/`
- Name test files `test_*.py`
- Use pytest fixtures for setup
- Aim for >80% coverage

```python
# tests/test_example.py
import pytest
from oclawma.example import my_function

def test_my_function():
    assert my_function("input") == "expected"

@pytest.mark.asyncio
async def test_async_function():
    result = await my_async_function()
    assert result == "expected"
```

## Code Style

We use:

- **black**: Code formatting (line length: 100)
- **ruff**: Fast linting
- **mypy**: Type checking

### Formatting

```bash
# Format all code
black src tests

# Check formatting (CI)
black --check src tests
```

### Linting

```bash
# Run linter
ruff check src tests

# Auto-fix issues
ruff check --fix src tests
```

### Type Checking

```bash
# Run type checker
mypy src
```

### Style Guidelines

- Use type hints for all functions
- Docstrings for public APIs (Google style)
- Maximum line length: 100
- Use f-strings for formatting

```python
def my_function(param: str, optional: int = 0) -> dict:
    """Short description.
    
    Longer description if needed.
    
    Args:
        param: Description of param
        optional: Description of optional param
        
    Returns:
        Description of return value
        
    Raises:
        ValueError: When invalid input
    """
    if not param:
        raise ValueError("param is required")
    return {"result": f"Processed {param}"}
```

## Commit Messages

Use conventional commits format:

```
type(scope): subject

body (optional)

footer (optional)
```

Types:
- `feat`: New feature
- `fix`: Bug fix
- `docs`: Documentation only
- `style`: Formatting changes
- `refactor`: Code restructuring
- `test`: Adding/updating tests
- `chore`: Maintenance tasks

Examples:
```
feat(skills): add kubernetes skill

fix(providers): handle kimi rate limiting

docs: update installation guide

test(session): add context budget tests
```

## Pull Requests

1. **Update documentation** if needed
2. **Add tests** for new features
3. **Ensure CI passes** (tests, linting, type checking)
4. **Fill out the PR template**
5. **Link related issues**

### PR Checklist

- [ ] Tests added/updated
- [ ] Documentation updated
- [ ] Code formatted with black
- [ ] Linting passes with ruff
- [ ] Type checking passes with mypy
- [ ] CHANGELOG.md updated (if applicable)

### Review Process

1. Maintainers will review within a few days
2. Address review comments
3. Squash commits if requested
4. Merge when approved

## Documentation

Documentation lives in `docs/`:

- `docs/installation.md` - Installation guide
- `docs/configuration.md` - Configuration reference
- `docs/skill-development.md` - Skill development guide
- `docs/architecture.md` - Architecture overview
- `docs/api-reference.md` - API documentation

### Documentation Style

- Use Markdown
- Include code examples
- Keep line length reasonable (<100)
- Use descriptive headers

### Building Docs

```bash
# Install docs dependencies
pip install mkdocs mkdocs-material

# Serve locally
mkdocs serve

# Build
mkdocs build
```

## Release Process

1. Update version in `pyproject.toml`
2. Update `CHANGELOG.md`
3. Create a git tag:
   ```bash
   git tag v0.1.0
   git push origin v0.1.0
   ```
4. GitHub Actions will build and publish to PyPI

## Getting Help

- **Discussions**: [GitHub Discussions](https://github.com/openclaw/oclawma/discussions)
- **Issues**: [GitHub Issues](https://github.com/openclaw/oclawma/issues)
- **Discord**: [OpenClaw Discord](https://discord.gg/openclaw)

## Recognition

Contributors will be:
- Listed in `CONTRIBUTORS.md`
- Mentioned in release notes
- Added to the project's hall of fame

Thank you for contributing! 🦀
