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

Fork the repository on GitHub

Clone your fork locally:

git clone https://github.com/YOUR_USERNAME/pr-assistant.git
cd pr-assistant

Install development dependencies:
```
pip install -e ".[dev]"
```
Install pre-commit hooks:
```
pre-commit install
```

Create a feature branch:

git checkout -b feature/your-feature-name

Development Workflow

Making Changes

Write tests first - Follow TDD when possible
Keep changes focused - One feature/fix per PR
Follow code style - Use Black for formatting
Add documentation - Update docstrings and README as needed
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:

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:

pytest

Run with coverage:

pytest --cov=pr --cov-report=html

Run specific test file:

pytest tests/test_tools.py

Run specific test:

pytest tests/test_tools.py::TestFilesystemTools::test_read_file

Code Quality Checks

Before committing, run:

# 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

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

Adding a New Configuration Option

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

Adding a New Command

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

Plugin Development

Plugins should be self-contained Python files:

# 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

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:

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

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

PR Template

## 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

Automated checks must pass
At least one maintainer review required
Address all review comments
Squash commits if requested
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:

Step 1
Step 2
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! 🎉