CONTRIBUTING.md

Contributing to Compiler Copilot

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

Table of Contents

1. Code of Conduct
2. Getting Started
3. Development Setup
4. Project Structure
5. Making Changes
6. Testing
7. Submitting Changes
8. Coding Standards

Code of Conduct

• Be respectful and inclusive
• Focus on constructive feedback
• Help others learn and grow
• Maintain a professional environment

Getting Started

1. Fork the repository

2. Clone your fork:

   git clone https://github.com/your-username/CompilerCopilot.git
   cd CompilerCopilot

3. Set up development environment:

   ./setup.sh
   source venv/bin/activate

4. Create a branch:

   git checkout -b feature/your-feature-name

Development Setup

Prerequisites

• Python 3.9 or higher
• GDB or LLDB installed
• Clang/LLVM toolchain
• Git

Environment Configuration

1. Copy the example configuration:

   cp config/env.example config/.env

2. Edit config/.env with your settings:

   • Set debugger paths
   • Configure compiler toolchain paths
   • Add LLM API credentials (for testing)

Installing Dependencies

pip install -r requirements.txt
pip install -r requirements-dev.txt  # Development dependencies

Project Structure

CompilerCopilot/
├── src/
│   ├── mcp/              # MCP server implementation
│   ├── debugger/         # Debugger wrappers
│   ├── compiler/         # Compiler analysis tools
│   ├── llm/              # LLM integration
│   └── shell/            # Interactive shell
├── config/               # Configuration files
├── examples/             # Example code and workflows
├── tests/                # Test suite
└── docs/                 # Additional documentation

Making Changes

Adding a New Feature

1. Create an issue describing the feature
2. Discuss the approach with maintainers
3. Implement the feature following coding standards
4. Add tests for the new functionality
5. Update documentation as needed

Fixing a Bug

1. Create an issue describing the bug
2. Write a test that reproduces the bug
3. Fix the bug
4. Verify the test passes
5. Submit a pull request

Adding a New Debugger

To add support for a new debugger (e.g., DBX):

1. Create src/debugger/dbx_wrapper.py:

   from ..config import Config
   
   class DBXWrapper:
       def __init__(self, config: Config):
           self.config = config
       
       async def start(self, program: str, args=None):
           # Implementation
           pass
       
       async def execute(self, command: str):
           # Implementation
           pass

2. Update src/mcp/server.py to include the new debugger

3. Add configuration options in src/config.py

4. Write tests in tests/test_dbx_wrapper.py

5. Update documentation

Adding a New LLM Provider

To add a new LLM provider:

1. Update src/llm/client.py:

   def _init_new_provider(self):
       """Initialize new provider client."""
       # Implementation
   
   async def _generate_new_provider(self, prompt: str) -> str:
       """Generate using new provider."""
       # Implementation

2. Add provider configuration in src/config.py

3. Update requirements.txt with provider SDK

4. Add tests

5. Update documentation

Testing

Running Tests

# Run all tests
pytest

# Run specific test file
pytest tests/test_debugger.py

# Run with coverage
pytest --cov=src tests/

# Run specific test
pytest tests/test_debugger.py::test_gdb_start

Writing Tests

Example test structure:

import pytest
from src.debugger.gdb_wrapper import GDBWrapper
from src.config import get_config

@pytest.fixture
def config():
    return get_config()

@pytest.fixture
def gdb_wrapper(config):
    return GDBWrapper(config)

@pytest.mark.asyncio
async def test_gdb_start(gdb_wrapper):
    result = await gdb_wrapper.start("test_program")
    assert "GDB started" in result

Test Coverage

• Aim for >80% code coverage
• Test edge cases and error conditions
• Mock external dependencies (debuggers, LLMs)
• Test async operations properly

Submitting Changes

Pull Request Process

1. Update your branch:

   git fetch upstream
   git rebase upstream/main

2. Run tests:

   pytest

3. Commit your changes:

   git add .
   git commit -m "feat: add support for DBX debugger"

4. Push to your fork:

   git push origin feature/your-feature-name

5. Create a pull request on GitHub

Commit Message Format

Follow conventional commits:

<type>(<scope>): <subject>

<body>

<footer>

Types:

• feat: New feature
• fix: Bug fix
• docs: Documentation changes
• style: Code style changes (formatting)
• refactor: Code refactoring
• test: Adding or updating tests
• chore: Maintenance tasks

Examples:

feat(debugger): add DBX debugger support

Implement DBX wrapper with basic debugging commands.
Includes start, execute, and analyze_crash methods.

Closes #123

fix(llm): handle timeout errors gracefully

Add proper error handling for LLM API timeouts.
Return user-friendly error messages instead of crashing.

Fixes #456

Pull Request Guidelines

• Title: Clear and descriptive
• Description: Explain what and why
• Link issues: Reference related issues
• Tests: Include test results
• Documentation: Update if needed
• Screenshots: For UI changes

Coding Standards

Python Style

Follow PEP 8 with these specifics:

• Line length: 100 characters
• Indentation: 4 spaces
• Quotes: Double quotes for strings
• Imports: Grouped and sorted

  # Standard library
  import os
  import sys
  
  # Third-party
  import pexpect
  from rich.console import Console
  
  # Local
  from ..config import Config

Type Hints

Use type hints for all functions:

from typing import Optional, List, Dict

async def execute(self, command: str) -> str:
    """Execute a command and return output."""
    pass

def process_data(items: List[int]) -> Dict[str, int]:
    """Process items and return statistics."""
    pass

Documentation

Docstrings

Use Google-style docstrings:

def calculate_sum(numbers: List[int]) -> int:
    """Calculate the sum of a list of numbers.
    
    Args:
        numbers: List of integers to sum.
    
    Returns:
        The sum of all numbers.
    
    Raises:
        ValueError: If the list is empty.
    
    Example:
        >>> calculate_sum([1, 2, 3])
        6
    """
    if not numbers:
        raise ValueError("List cannot be empty")
    return sum(numbers)

Comments

• Explain why, not what
• Keep comments up-to-date
• Use TODO comments for future work:

  # TODO(username): Add support for remote debugging

Error Handling

# Good
try:
    result = await debugger.execute(command)
except TimeoutError:
    logger.error(f"Command timed out: {command}")
    return "Command execution timed out"
except Exception as e:
    logger.exception(f"Unexpected error: {e}")
    raise

# Bad
try:
    result = await debugger.execute(command)
except:
    pass

Async/Await

• Use async/await for I/O operations
• Don't block the event loop
• Use asyncio.create_task() for concurrent operations

# Good
async def process_multiple_files(files: List[str]):
    tasks = [process_file(f) for f in files]
    results = await asyncio.gather(*tasks)
    return results

# Bad
async def process_multiple_files(files: List[str]):
    results = []
    for f in files:
        result = await process_file(f)  # Sequential, not concurrent
        results.append(result)
    return results

Review Process

1. Automated checks must pass (tests, linting)
2. Code review by at least one maintainer
3. Address feedback and update PR
4. Approval from maintainer
5. Merge by maintainer

Getting Help

• Issues: Open an issue for bugs or features
• Discussions: Use GitHub Discussions for questions
• Documentation: Check ARCHITECTURE.md and README.md

Recognition

Contributors will be:

• Listed in CONTRIBUTORS.md
• Mentioned in release notes
• Credited in documentation

Thank you for contributing to Compiler Copilot! 🎉