Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
439 lines (328 loc) · 10.7 KB

CONTRIBUTING.md

File metadata and controls

439 lines (328 loc) · 10.7 KB

Contributing to BotForge RAG

Thank you for your interest in contributing to BotForge RAG! This document provides guidelines and information for contributors.

📋 Table of Contents

📜 Code of Conduct

We are committed to providing a welcoming and inclusive environment for all contributors. Please read and follow our Code of Conduct.

Our Standards

  • Use welcoming and inclusive language
  • Be respectful of differing viewpoints and experiences
  • Gracefully accept constructive criticism
  • Focus on what is best for the community
  • Show empathy towards other community members

🚀 Development Setup

Prerequisites

  • Python 3.9+ (3.11+ recommended)
  • PostgreSQL 15+
  • Redis 7+
  • Git
  • uv (recommended) or pip

Local Environment Setup

  1. Clone the repository

    git clone https://github.com/your-org/botforge-rag.git
cd botforge-rag

  2. Install dependencies

    # Using uv (recommended)
uv sync --all-extras

# Or using pip
pip install -e ".[dev,test]"

  3. Set up pre-commit hooks

    pre-commit install

  4. Configure environment

    cp .env.example .env
# Edit .env with your local configuration

  5. Initialize database

    # Start PostgreSQL and Redis services
# Then run database initialization
python scripts/init_db.py

  6. Run tests

    pytest tests/ -v

  7. Start development server

    PYTHONPATH=./src uvicorn botforge.main:app --reload --port 8000

Development Tools

  • Code Formatting: Black
  • Import Sorting: isort
  • Linting: flake8, pylint
  • Type Checking: mypy
  • Testing: pytest
  • Pre-commit: Automated code quality checks

🔄 Development Workflow

Branch Strategy

  • main: Production-ready code
  • develop: Integration branch for features
  • feature/*: New features and enhancements
  • bugfix/*: Bug fixes
  • hotfix/*: Critical production fixes

Git Workflow

  1. Create feature branch

    git checkout -b feature/your-feature-name

  2. Make changes with clear commits

    git add .
git commit -m "feat: add new MCP integration feature"

  3. Keep branch updated

    git fetch origin
git rebase origin/develop

  4. Push and create pull request

    git push origin feature/your-feature-name

Commit Message Convention

Follow Conventional Commits:

<type>[optional scope]: <description>

[optional body]

[optional footer(s)]

Types:

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

Examples:

feat(mcp): add external tool registration endpoint
fix(vector): resolve embedding dimension mismatch
docs(api): update endpoint documentation
test(services): add unit tests for intent detection

📏 Code Standards

Python Code Style

  • Formatter: Black (line length: 88)
  • Import sorting: isort
  • Docstring style: Google format
  • Type hints: Required for all function signatures

Code Quality Rules

  1. Async/Await: Use async/await for all I/O operations
  2. Error Handling: Comprehensive error handling with custom exceptions
  3. Logging: Use structured logging throughout
  4. Type Safety: Full type annotations required
  5. Dependencies: Minimize external dependencies, justify additions

Example Code Style

from typing import Dict, List, Optional
import asyncio
from botforge.core.logger import log

async def process_query(
    user_id: str,
    bot_id: str,
    query: str,
    model: str = "gpt-3.5-turbo"
) -> Dict[str, Any]:
    """Process user query with intent detection and routing.
    
    Args:
        user_id: Unique identifier for the user
        bot_id: Unique identifier for the bot
        query: User's input query
        model: OpenAI model to use for processing
        
    Returns:
        Dictionary containing response and metadata
        
    Raises:
        ValueError: If required parameters are missing
        ProcessingError: If query processing fails
    """
    try:
        log.info(f"Processing query for user {user_id}, bot {bot_id}")
        
        # Implementation here
        result = await some_async_operation()
        
        return {
            "response": result,
            "metadata": {"model": model, "timestamp": time.time()}
        }
        
    except Exception as e:
        log.error(f"Query processing failed: {e}")
        raise ProcessingError(f"Failed to process query: {e}") from e

🧪 Testing Guidelines

Test Structure

tests/
├── unit/           # Unit tests for individual components
├── integration/    # Integration tests for component interaction
├── e2e/           # End-to-end tests for complete workflows
├── fixtures/      # Test data and fixtures
└── conftest.py    # Pytest configuration

Testing Requirements

  1. Unit Tests: All new functions and methods
  2. Integration Tests: API endpoints and service interactions
  3. Test Coverage: Minimum 80% code coverage
  4. Test Data: Use fixtures for consistent test data
  5. Async Testing: Use pytest-asyncio for async functions

Example Test

import pytest
from unittest.mock import AsyncMock, patch
from botforge.services.vector_query import VectorQueryService

class TestVectorQueryService:
    @pytest.fixture
    async def service(self):
        return VectorQueryService()
    
    @pytest.mark.asyncio
    async def test_query_processing(self, service):
        """Test basic query processing functionality."""
        # Arrange
        query = "What is machine learning?"
        expected_intent = "information_retrieval"
        
        # Act
        result = await service.process_query(
            user_id="test-user",
            bot_id="test-bot",
            query=query
        )
        
        # Assert
        assert result["intent"] == expected_intent
        assert "response" in result
        assert len(result["response"]) > 0
    
    @pytest.mark.asyncio
    async def test_error_handling(self, service):
        """Test error handling for invalid inputs."""
        with pytest.raises(ValueError):
            await service.process_query("", "test-bot", "test query")

Running Tests

# Run all tests
pytest

# Run with coverage
pytest --cov=src --cov-report=html

# Run specific test file
pytest tests/unit/test_vector_query.py

# Run tests matching pattern
pytest -k "test_mcp"

# Run tests with verbose output
pytest -v -s

📚 Documentation

Documentation Standards

  1. API Documentation: OpenAPI/Swagger specifications
  2. Code Documentation: Comprehensive docstrings
  3. Architecture Documentation: High-level system design
  4. User Guides: Step-by-step integration guides

Docstring Format

Use Google-style docstrings:

def calculate_similarity(vector1: List[float], vector2: List[float]) -> float:
    """Calculate cosine similarity between two vectors.
    
    Args:
        vector1: First vector as list of floats
        vector2: Second vector as list of floats
        
    Returns:
        Cosine similarity score between 0 and 1
        
    Raises:
        ValueError: If vectors have different dimensions
        
    Example:
        >>> calculate_similarity([1, 0, 0], [0, 1, 0])
        0.0
    """

Documentation Updates

  • Update API documentation for endpoint changes
  • Add examples for new features
  • Update README for significant changes
  • Include migration guides for breaking changes

🔍 Pull Request Process

Before Submitting

  1. Code Quality: Ensure all checks pass

    pre-commit run --all-files

  2. Tests: Verify all tests pass

    pytest tests/ -v

  3. Documentation: Update relevant documentation

  4. Changelog: Add entry to CHANGELOG.md

Pull Request Template

## Description
Brief description of changes and motivation.

## Type of Change
- [ ] Bug fix (non-breaking change that fixes an issue)
- [ ] New feature (non-breaking change that adds functionality)
- [ ] Breaking change (fix or feature that would cause existing functionality to not work as expected)
- [ ] Documentation update

## Testing
- [ ] Unit tests added/updated
- [ ] Integration tests added/updated
- [ ] Manual testing completed

## Checklist
- [ ] Code follows style guidelines
- [ ] Self-review completed
- [ ] Documentation updated
- [ ] Tests added and passing
- [ ] No new warnings introduced

Review Process

  1. Automated Checks: All CI checks must pass
  2. Code Review: At least one maintainer approval required
  3. Testing: New features require comprehensive tests
  4. Documentation: API changes require documentation updates

🐛 Issue Reporting

Bug Reports

Include the following information:

  • Environment: OS, Python version, dependency versions
  • Steps to Reproduce: Detailed reproduction steps
  • Expected Behavior: What should happen
  • Actual Behavior: What actually happens
  • Error Messages: Full error messages and stack traces
  • Additional Context: Any other relevant information

Feature Requests

Include the following information:

  • Problem Description: What problem does this solve?
  • Proposed Solution: How should it work?
  • Alternatives: Other solutions considered
  • Implementation Ideas: Technical approach if you have ideas

Issue Labels

  • bug: Something isn't working
  • enhancement: New feature or request
  • documentation: Improvements or additions to documentation
  • good first issue: Good for newcomers
  • help wanted: Extra attention is needed
  • priority-high: High priority issue

🤝 Community

Getting Help

  • GitHub Discussions: For questions and general discussion
  • GitHub Issues: For bug reports and feature requests
  • Documentation: Check existing documentation first
  • Code Review: Participate in code reviews

Recognition

Contributors will be recognized in:

  • README.md contributors section
  • Release notes for significant contributions
  • Annual contributor recognition

📞 Contact

Thank you for contributing to BotForge RAG! 🚀