# Contributing to PR Assistant

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

## Code of Conduct

- Be respectful and inclusive
- Welcome newcomers and encourage diverse perspectives
- Focus on constructive feedback
- Maintain professionalism in all interactions

## Getting Started

### Prerequisites

- Python 3.8 or higher
- Git
- OpenRouter API key (for testing)

### Development Setup

1. Fork the repository on GitHub
2. Clone your fork locally:
   ```bash
   git clone https://github.com/YOUR_USERNAME/pr-assistant.git
   cd pr-assistant
   ```

3. Install development dependencies:
   ```bash
   pip install -e ".[dev]"
   ```

4. Install pre-commit hooks:
   ```bash
   pre-commit install
   ```

5. Create a feature branch:
   ```bash
   git checkout -b feature/your-feature-name
   ```

## Development Workflow

### Making Changes

1. **Write tests first** - Follow TDD when possible
2. **Keep changes focused** - One feature/fix per PR
3. **Follow code style** - Use Black for formatting
4. **Add documentation** - Update docstrings and README as needed
5. **Update changelog** - Add entry to CHANGELOG.md

### Code Style

We follow PEP 8 with some modifications:

- Line length: 100 characters (not 80)
- Use Black for automatic formatting
- Use descriptive variable names
- Add type hints where beneficial
- Write docstrings for all public functions/classes

Example:

```python
def process_data(input_data: str, max_length: int = 100) -> Dict[str, Any]:
    """
    Process input data and return structured result.

    Args:
        input_data: The raw input string to process
        max_length: Maximum length of output (default: 100)

    Returns:
        Dictionary containing processed data

    Raises:
        ValidationError: If input_data is invalid
    """
    # Implementation here
    pass
```

### Running Tests

Run all tests:
```bash
pytest
```

Run with coverage:
```bash
pytest --cov=pr --cov-report=html
```

Run specific test file:
```bash
pytest tests/test_tools.py
```

Run specific test:
```bash
pytest tests/test_tools.py::TestFilesystemTools::test_read_file
```

### Code Quality Checks

Before committing, run:

```bash
# Format code
black pr tests

# Check linting
flake8 pr tests --max-line-length=100 --ignore=E203,W503

# Type checking
mypy pr --ignore-missing-imports

# Run all checks
pre-commit run --all-files
```

## Project Structure

### Adding New Features

#### Adding a New Tool

1. Implement the tool function in appropriate `pr/tools/*.py` file
2. Add tool definition to `pr/tools/base.py:get_tools_definition()`
3. Add function mapping in `pr/core/assistant.py:execute_tool_calls()`
4. Add function mapping in `pr/autonomous/mode.py:execute_single_tool()`
5. Write tests in `tests/test_tools.py`
6. Update documentation

#### Adding a New Configuration Option

1. Add to default config in `pr/core/config_loader.py`
2. Update config documentation in README.md
3. Add validation if needed in `pr/core/validation.py`
4. Write tests

#### Adding a New Command

1. Add handler to `pr/commands/handlers.py`
2. Update help text in `pr/__main__.py`
3. Write tests
4. Update README.md with command documentation

### Plugin Development

Plugins should be self-contained Python files:

```python
# Plugin structure
def tool_function(args):
    """Implementation"""
    pass


def register_tools():
    """Return list of tool definitions"""
    return [...]
```

## Testing Guidelines

### Test Organization

- `tests/test_*.py` - Test files matching source files
- `tests/conftest.py` - Shared fixtures
- Use descriptive test names: `test_<function>_<scenario>_<expected_result>`

### Writing Good Tests

```python
def test_read_file_with_valid_path_returns_content(temp_dir):
    # Arrange
    filepath = os.path.join(temp_dir, "test.txt")
    expected_content = "Hello, World!"
    write_file(filepath, expected_content)

    # Act
    result = read_file(filepath)

    # Assert
    assert expected_content in result
```

### Test Coverage

- Aim for >80% code coverage
- Cover edge cases and error conditions
- Test both success and failure paths

## Documentation

### Docstring Format

Use Google-style docstrings:

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

    Longer description with more details about what the function
    does and how it works.

    Args:
        param1: Description of param1
        param2: Description of param2

    Returns:
        Description of return value

    Raises:
        ValueError: Description of when this is raised
    """
    pass
```

### Updating Documentation

When adding features, update:

- Function/class docstrings
- README.md
- CHANGELOG.md
- Code comments (where necessary)

## Pull Request Process

### Before Submitting

1. ✅ All tests pass
2. ✅ Code is formatted with Black
3. ✅ Linting passes (flake8)
4. ✅ No type errors (mypy)
5. ✅ Documentation is updated
6. ✅ CHANGELOG.md is updated
7. ✅ Commits are clean and descriptive

### PR Template

```markdown
## Description
Brief description of changes

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

## Changes Made
- Change 1
- Change 2

## Testing
- Test scenario 1
- Test scenario 2

## Checklist
- [ ] Tests pass
- [ ] Code formatted with Black
- [ ] Documentation updated
- [ ] CHANGELOG.md updated
```

### Review Process

1. Automated checks must pass
2. At least one maintainer review required
3. Address all review comments
4. Squash commits if requested
5. Maintainer will merge when approved

## Commit Messages

Follow conventional commits:

```
type(scope): subject

body (optional)

footer (optional)
```

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

Examples:
```
feat(tools): add text analysis tool

fix(api): handle timeout errors properly

docs(readme): update installation instructions
```

## Reporting Bugs

### Bug Report Template

**Description:**
Clear description of the bug

**To Reproduce:**
1. Step 1
2. Step 2
3. See error

**Expected Behavior:**
What should happen

**Actual Behavior:**
What actually happens

**Environment:**
- OS:
- Python version:
- PR Assistant version:

**Additional Context:**
Logs, screenshots, etc.

## Feature Requests

**Feature Description:**
What feature would you like?

**Use Case:**
Why is this needed?

**Proposed Solution:**
How might this work?

**Alternatives:**
Other approaches considered

## Questions?

- Open an issue for questions
- Check existing issues first
- Tag with `question` label

## License

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

---

Thank you for contributing to PR Assistant! 🎉