Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
334 lines (246 loc) · 9.12 KB

CONTRIBUTING.md

File metadata and controls

334 lines (246 loc) · 9.12 KB

Contributing to Codex Bridge

Thank you for your interest in contributing to Codex Bridge! We welcome contributions from the community and are excited to work with you.

🚀 Getting Started

Prerequisites

Before contributing, make sure you have:

  • Python 3.9 or higher
  • Codex CLI installed and authenticated
  • Git for version control
  • A GitHub account

Development Setup

  1. Fork the repository on GitHub

  2. Clone your fork locally:

    git clone https://github.com/YOUR_USERNAME/codex-bridge.git
cd codex-bridge

  3. Set up the development environment:

    # Install in development mode
pip install -e .

# Verify installation
python -m src --help

  4. Verify Codex CLI is working:

    codex --version
codex auth login  # if not already authenticated

  5. Create a feature branch:

    git checkout -b feature/your-feature-name

🔄 Development Workflow

Making Changes

  1. Make your changes in small, logical commits

  2. Test your changes thoroughly:

    # Test the MCP server directly
python -m src

# Test integration with Claude Code (if available)
./start_server_dev.sh

  3. Follow code style guidelines (see below)

  4. Update documentation if needed

Code Style Guidelines

  • Python: Follow PEP 8 style guide
  • Line length: Maximum 88 characters (Black formatter default)
  • Imports: Group imports logically (standard library, third-party, local)
  • Docstrings: Use clear, descriptive docstrings for functions and classes
  • Type hints: Include type hints for function parameters and return values

Example code style:

from typing import Optional, List
import subprocess
import json

def consult_codex(
    query: str, 
    directory: str = ".", 
    format: str = "json",
    timeout: Optional[int] = None
) -> str:
    """
    Send a query to Codex CLI.
    
    Args:
        query: The question or prompt to send
        directory: Working directory for the query
        format: Output format - "text", "json", or "code" (default: "json")
        timeout: Optional timeout in seconds (recommended: 60-120)
        
    Returns:
        Codex's response as a formatted string
        
    Raises:
        RuntimeError: If CLI is not available or query fails
    """
    # Implementation here...

📝 Types of Contributions

We welcome several types of contributions:

🐛 Bug Fixes

  • Fix existing bugs or issues
  • Improve error handling
  • Address edge cases

✨ Feature Enhancements

  • Add new MCP tools (with justification)
  • Improve existing tool functionality
  • Add configuration options

📚 Documentation

  • Improve README or other documentation
  • Add usage examples
  • Write tutorials or guides

🧪 Testing

  • Add test cases
  • Improve test coverage
  • Add integration tests

🔧 Infrastructure

  • Improve build process
  • Update dependencies
  • Enhance CI/CD

🔍 Pull Request Process

Before Submitting

  1. Ensure your code works with both development and production setups

  2. Write clear commit messages:

    feat: add support for custom timeout configuration

- Add timeout parameter to both MCP tools
- Update documentation with timeout examples
- Maintain backward compatibility with default 60s timeout

  3. Update relevant documentation

  4. Test thoroughly on your local setup

Submitting Your PR

  1. Push to your fork:

    git push origin feature/your-feature-name

  2. Create a Pull Request on GitHub with:

    • Clear title describing the change
    • Detailed description explaining:
      • What the change does
      • Why it's needed
      • How it was tested
      • Any breaking changes
    • Link related issues using Fixes #123 or Relates to #456

PR Review Process

  1. Automated checks will run (when available)
  2. Maintainer review will check:
    • Code quality and style
    • Functionality and correctness
    • Documentation updates
    • Backward compatibility
  3. Address feedback promptly and professionally
  4. Final approval and merge by maintainers

🚫 What We DON'T Accept

  • Changes that add unnecessary complexity
  • Features that duplicate existing functionality
  • Breaking changes without strong justification and migration path
  • Code that doesn't follow the project's simplicity philosophy
  • Contributions without proper testing

🗣️ Communication Guidelines

Reporting Issues

Use our issue templates for:

  • Bug reports: Include reproduction steps, environment details
  • Feature requests: Explain the use case and expected behavior
  • Questions: Use GitHub Discussions for general questions

Code Reviews

  • Be constructive and respectful in feedback
  • Explain the "why" behind suggestions
  • Learn from others and be open to feedback
  • Focus on the code, not the person

Community Standards

Please read our Code of Conduct for community interaction guidelines.

📋 Testing Guidelines

Automated Test Suite

We have a comprehensive test suite in the tests/ directory:

# Run the complete test suite
python tests/test_mcp_tools.py

# Test results are automatically generated
cat tests/TEST_RESULTS.md

Manual Testing Checklist

Before submitting, verify:

  • Core Functionality

    • MCP server starts without errors: python -m src
    • consult_codex tool works with basic queries (defaults to JSON format)
    • consult_codex_with_stdin tool works with stdin content
    • consult_codex_batch tool works for batch processing

  • Output Formats

    • Text format: Returns clean text response
    • JSON format: Returns valid JSON with proper structure
    • Code format: Extracts code blocks correctly

  • Environment Variables

    • CODEX_TIMEOUT configuration works (test with 120s timeout)
    • CODEX_SKIP_GIT_CHECK=true allows non-git directory usage
    • Default behavior enforces git repository check

  • Error Handling

    • Invalid format parameter returns JSON error
    • Invalid directory returns proper error
    • CLI not available scenario handled
    • All errors return consistent JSON structure

  • Performance

    • Response times reasonable (4-30 seconds typical)
    • No memory leaks during extended testing
    • Batch processing handles multiple queries efficiently

  • Documentation

    • Code changes have proper docstrings
    • README updates for new features
    • CHANGELOG.md updated with changes

Test Development

When adding new features:

  1. Add tests first (TDD approach recommended)

  2. Use the existing test structure:

    def test_new_feature():
    """Test description"""
    print("🧪 Testing new feature...")
    
    # Test implementation
    result = consult_codex(...)
    
    # Validation with clear output
    if condition:
        print("✅ New feature test passed")
    else:
        print("❌ New feature test failed")

  3. Include both success and failure cases

  4. Update tests/README.md with new test documentation

Integration Testing

Test with different environments:

  • Python versions: 3.10, 3.11, 3.12 (minimum 3.10)
  • Codex CLI versions: Latest stable release
  • Operating systems: macOS, Linux (Windows via WSL)
  • MCP clients: Claude Code, Cursor, VS Code extensions

Performance Testing

Monitor these metrics:

  • Response times: Should be consistent with documented ranges
  • Memory usage: Should remain stable during extended use
  • Error rates: Should be minimal under normal conditions
  • CLI integration: Should handle Codex CLI updates gracefully

🆘 Getting Help

Questions and Support

  • GitHub Discussions: For general questions and community discussion
  • GitHub Issues: For bug reports and feature requests
  • Documentation: Check existing docs first

Maintainer Contact

For sensitive issues or maintainer-specific questions, you can reach out through:

  • GitHub issues (preferred for transparency)
  • Email (for security issues only)

📚 Resources

Helpful Links

Development Tools

Recommended tools for development:

  • Code Editor: VS Code, PyCharm, or your preferred editor
  • Linting: flake8, black, or ruff
  • Type Checking: mypy
  • Git: For version control

🙏 Recognition

Contributors are recognized in:

  • GitHub contributor list
  • CHANGELOG.md for significant contributions
  • Special mentions for major features or fixes

Thank you for contributing to Codex Bridge! Your contributions help make this tool better for the entire community.

This contributing guide is inspired by open source best practices and will evolve as our community grows.