Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
209 lines (153 loc) · 4.16 KB

CONTRIBUTING.md

File metadata and controls

209 lines (153 loc) · 4.16 KB

Contributing to CAG System

Thank you for your interest in contributing to the Cache Augmentation Generation (CAG) system!

Getting Started

  1. Fork the repository
  2. Clone your fork: git clone <your-fork-url>
  3. Create a feature branch: git checkout -b feature/your-feature-name
  4. Set up the development environment (see docs/SETUP.md)

Development Workflow

1. Code Style

We follow PEP 8 and use automated tools:

# Format code
black src/ tests/

# Sort imports
isort src/ tests/

# Lint
flake8 src/ tests/

# Type check
mypy src/

2. Testing

Write tests for all new features:

# Run tests
pytest

# With coverage
pytest --cov=src --cov-report=html

# Watch mode (requires pytest-watch)
ptw

Test Guidelines:

  • Place tests in the tests/ directory
  • Mirror the source structure
  • Use descriptive test names
  • Aim for >80% code coverage

3. Commit Messages

Follow conventional commits:

type(scope): subject

body (optional)

footer (optional)

Types:

  • feat: New feature
  • fix: Bug fix
  • docs: Documentation changes
  • style: Code style changes (formatting)
  • refactor: Code refactoring
  • test: Test additions or changes
  • chore: Build process or auxiliary tool changes

Examples:

feat(cache): add Redis support for distributed caching

fix(api): handle empty file uploads correctly

docs(readme): update installation instructions

4. Pull Request Process

  1. Update documentation if needed
  2. Add tests for new functionality
  3. Ensure all tests pass
  4. Update CHANGELOG.md
  5. Create a pull request with a clear description

PR Title Format:

[Type] Brief description

PR Description Should Include:

  • What changes were made
  • Why the changes were necessary
  • Any breaking changes
  • Related issues (if applicable)

Code Organization

Directory Structure

src/cag/
├── api/          # API endpoints and routes
├── core/         # Core configuration and models
├── services/     # Business logic services
└── ui/           # User interfaces

Adding New Features

New Service

  1. Create file in src/cag/services/
  2. Add tests in tests/test_<service_name>.py
  3. Update src/cag/services/__init__.py if needed
  4. Document the service

New API Endpoint

  1. Add endpoint in src/cag/api/main.py or create route module
  2. Add request/response models in src/cag/core/models.py
  3. Add tests in tests/test_main.py
  4. Update API documentation in docs/API.md

New Configuration

  1. Add setting in src/cag/core/config.py
  2. Update .env.example
  3. Document in README.md

Testing Guidelines

Unit Tests

Test individual components in isolation:

def test_cache_manager_get():
    cache = CacheManager()
    cache.set("query", "response")
    result = cache.get("query")
    assert result is not None

Integration Tests

Test component interactions:

@pytest.mark.integration
def test_document_upload_flow():
    # Test full upload → process → store flow
    pass

Fixtures

Use pytest fixtures for common setup:

@pytest.fixture
def cag_service():
    return CAGService()

Documentation

Update documentation for:

  • New features
  • API changes
  • Configuration options
  • Breaking changes

Documentation Files:

  • README.md: Overview and quick start
  • docs/ARCHITECTURE.md: System design
  • docs/API.md: API reference
  • docs/SETUP.md: Setup instructions

Performance Considerations

  • Profile code for performance bottlenecks
  • Use caching appropriately
  • Optimize database queries
  • Consider async operations for I/O

Security

  • Never commit secrets or API keys
  • Validate all user inputs
  • Use parameterized queries
  • Follow OWASP guidelines
  • Report security issues privately

Questions?

  • Open an issue for bugs or feature requests
  • Start a discussion for questions
  • Check existing issues before creating new ones

Code of Conduct

  • Be respectful and inclusive
  • Provide constructive feedback
  • Focus on the code, not the person
  • Help others learn and grow

License

By contributing, you agree that your contributions will be licensed under the same license as the project (MIT).