Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
343 lines (265 loc) · 9.6 KB

CONTRIBUTING.md

File metadata and controls

343 lines (265 loc) · 9.6 KB

🤝 Contributing to Codestral AI Integration

Thank you for your interest in contributing to the Codestral AI Integration project! We welcome contributions from developers of all skill levels and backgrounds.

🌟 Ways to Contribute

🐛 Bug Reports

Found a bug? Help us improve by reporting it!

Before submitting a bug report:

  • Check if the issue already exists in Issues
  • Verify the bug with the latest version
  • Gather relevant information (OS, Python version, etc.)

When submitting a bug report, include:

  • Clear, descriptive title
  • Steps to reproduce the issue
  • Expected vs actual behavior
  • Error messages or screenshots
  • Environment details (OS, Python version, dependencies)

✨ Feature Requests

Have ideas for new features or improvements?

For feature requests:

  • Check existing feature requests
  • Clearly describe the problem you're solving
  • Explain your proposed solution
  • Consider backwards compatibility
  • Include use cases and examples

💻 Code Contributions

Ready to contribute code? Here's how to get started:

1. Development Environment Setup

# Fork and clone the repository
git clone https://github.com/your-username/codestral-ai-integration.git
cd codestral-ai-integration

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

# Install development dependencies
pip install -r requirements-dev.txt

# Install the package in development mode
pip install -e .

2. Making Changes

# Create a feature branch
git checkout -b feature/your-feature-name

# Make your changes
# ... code, code, code ...

# Run tests
python -m pytest

# Format code
black .

# Lint code
flake8 .

# Type check
mypy .

3. Submitting Changes

# Commit your changes
git add .
git commit -m "feat: add awesome new feature"

# Push to your fork
git push origin feature/your-feature-name

# Create a Pull Request on GitHub

🎯 Development Guidelines

Code Style

  • Python: Follow PEP 8
  • Formatting: Use black for consistent formatting
  • Linting: Use flake8 for code quality checks
  • Type Hints: Add type hints for better code clarity
  • Docstrings: Use Google-style docstrings for functions and classes

Example:

def process_completion(
    prompt: str, 
    max_tokens: int = 1000,
    temperature: float = 0.1
) -> Dict[str, Any]:
    """Process a completion request with Codestral.
    
    Args:
        prompt: The input prompt for code generation
        max_tokens: Maximum tokens to generate
        temperature: Sampling temperature for randomness
        
    Returns:
        Dictionary containing the completion response
        
    Raises:
        APIError: If the Codestral API request fails
    """
    # Implementation here
    pass

Testing

  • Write tests for new features using pytest
  • Maintain or improve test coverage
  • Include both unit tests and integration tests
  • Test edge cases and error conditions

Test Structure:

def test_completion_with_valid_input():
    """Test completion with valid input parameters."""
    # Arrange
    prompt = "def fibonacci(n):"
    
    # Act
    result = codestral_complete(prompt)
    
    # Assert
    assert result is not None
    assert "def fibonacci" in result

Documentation

  • Update docstrings for any changed functions
  • Add examples for new features
  • Update README.md if adding user-facing features
  • Include type hints in function signatures

Commit Messages

Use Conventional Commits format:

<type>[optional scope]: <description>

[optional body]

[optional footer(s)]

Types:

  • feat: New feature
  • fix: Bug fix
  • docs: Documentation only changes
  • style: Changes that don't affect code meaning
  • refactor: Code change that neither fixes a bug nor adds a feature
  • perf: Performance improvements
  • test: Adding missing tests
  • chore: Changes to build process or auxiliary tools

Examples:

feat(cli): add streaming mode for real-time responses
fix(proxy): handle connection timeout errors properly
docs: update installation instructions for Windows
test(cli): add tests for interactive mode

🏗️ Project Architecture

Core Components

1. CLI Module (cli/)

  • Purpose: Direct command-line interface to Codestral
  • Key Files: main.py
  • Responsibilities: User interaction, prompt processing, response formatting

2. Proxy Module (proxy/)

  • Purpose: OpenAI-compatible API proxy
  • Key Files: server.py, simple_server.py
  • Responsibilities: API compatibility, request translation, response formatting

3. Scripts (scripts/)

  • Purpose: Utility and setup scripts
  • Key Files: start-codestral-services.sh
  • Responsibilities: Service management, installation helpers

Adding New Features

For CLI Features:

  1. Add command-line arguments in cli/main.py
  2. Implement the feature logic
  3. Add appropriate error handling
  4. Update help text and documentation
  5. Add tests in tests/test_cli.py

For Proxy Features:

  1. Add new endpoints in proxy/server.py
  2. Implement request/response handling
  3. Ensure OpenAI API compatibility
  4. Add error handling and validation
  5. Add tests in tests/test_proxy.py

🧪 Testing Guidelines

Test Categories

  1. Unit Tests: Test individual functions/methods
  2. Integration Tests: Test component interactions
  3. API Tests: Test external API interactions (mocked)
  4. End-to-End Tests: Test complete workflows

Running Tests

# Run all tests
python -m pytest

# Run with coverage
python -m pytest --cov=src

# Run specific test file
python -m pytest tests/test_cli.py

# Run with verbose output
python -m pytest -v

# Run tests matching a pattern
python -m pytest -k "test_completion"

Test Environment

  • Use pytest.fixture for setup/teardown
  • Mock external API calls using unittest.mock
  • Test with different Python versions when possible
  • Include tests for error conditions

📚 Documentation Standards

Code Documentation

  • All public functions must have docstrings
  • Use Google-style docstrings
  • Include type hints for parameters and return values
  • Document exceptions that may be raised

User Documentation

  • Keep README.md up to date with new features
  • Add examples for new functionality
  • Update installation instructions if needed
  • Include troubleshooting tips for common issues

🔄 Pull Request Process

Before Submitting

  • Code follows project style guidelines
  • Tests pass locally (python -m pytest)
  • Code is properly formatted (black .)
  • No linting errors (flake8 .)
  • Documentation is updated
  • Commit messages follow conventional format

PR Checklist

  • Clear, descriptive title
  • Detailed description of changes
  • Link to related issues
  • Screenshots/examples if applicable
  • Breaking changes noted
  • Tests added/updated

Review Process

  1. Automated Checks: CI/CD will run tests and linting
  2. Code Review: Maintainers will review the code
  3. Feedback: Address any requested changes
  4. Approval: PR will be merged after approval

🎯 Areas for Contribution

High Priority

  • 🚀 Performance Optimizations: Improve response times
  • 🔒 Security Enhancements: Secure API key handling
  • 🧪 Test Coverage: Increase test coverage to 95%+
  • 📱 Cross-Platform Support: Improve Windows compatibility

Medium Priority

  • 🎨 UI Improvements: Better CLI output formatting
  • 🔧 Configuration Management: Better config file support
  • 📊 Metrics and Monitoring: Add usage analytics
  • 🐳 Containerization: Docker support

Nice to Have

  • 🌐 Web Interface: Optional web UI for the proxy
  • 📱 Mobile Support: Consider mobile-friendly APIs
  • 🎮 Plugin System: Support for custom plugins
  • 🔄 Streaming Responses: Real-time response streaming

🏆 Recognition

Contributors will be recognized in several ways:

  • 📝 CONTRIBUTORS.md: Listed in the contributors file
  • 🎉 Release Notes: Major contributions mentioned in releases
  • 💫 GitHub Profile: Contributions visible on your GitHub profile
  • 🏅 Special Thanks: Outstanding contributors get special recognition

🤔 Need Help?

Getting Started

Getting Help

  • 💬 Discussions: For general questions and brainstorming
  • 🐛 Issues: For bug reports and feature requests
  • 📧 Email: For sensitive matters (security, etc.)

Community Guidelines

  • Be respectful and inclusive
  • Help others learn and grow
  • Provide constructive feedback
  • Follow our Code of Conduct

🚀 Getting Your First Contribution Merged

  1. Start Small: Pick a good first issue or fix a typo
  2. Ask Questions: Don't hesitate to ask for clarification
  3. Follow Guidelines: Use our templates and guidelines
  4. Be Patient: Reviews take time, but we'll get to your PR
  5. Iterate: Address feedback promptly and professionally

📞 Contact

Thank you for contributing to Codestral AI Integration! 🎉

Together, we're making AI-powered coding more accessible to everyone.