Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
309 lines (223 loc) · 7.27 KB

CONTRIBUTING.md

File metadata and controls

309 lines (223 loc) · 7.27 KB

Contributing to Code Assistant Manager

Thank you for your interest in contributing to code-assistant-manager! This document provides guidelines and instructions for contributing to the project.

Table of Contents

Getting Started

  1. Fork the repository on GitHub
  2. Clone your fork locally: 
    git clone https://github.com/your-username/code-assistant-manager.git
cd code-assistant-manager
  3. Add the upstream repository: 
    git remote add upstream https://github.com/yourorg/code-assistant-manager.git

Development Setup

Prerequisites

  • Python 3.9 or higher
  • pip and virtualenv
  • Git
  • Node.js and npm (for some AI coding assistants)

Setting Up Development Environment

  1. Create and activate a virtual environment:

    python3 -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

  2. Install the package in development mode with all dependencies:

    make dev-install

    Or manually:

    pip install -e ".[dev]"
pre-commit install

  3. Verify the installation:

    code-assistant-manager --version
pytest tests/ -v

Code Quality Standards

We use automated code quality tools to maintain consistent, high-quality code. These tools are enforced via pre-commit hooks.

Tools Used

  • Black: Code formatting (line length: 88)
  • isort: Import sorting (compatible with Black)
  • Flake8: Linting with plugins (bugbear, comprehensions, simplify)
  • mypy: Type checking
  • Bandit: Security vulnerability scanning
  • interrogate: Docstring coverage checking

Running Quality Checks

Use the Makefile for convenience:

# Format code automatically
make format

# Check formatting without changes
make format-check

# Run linting
make lint

# Run type checking
make type-check

# Run security checks
make security

# Run all checks (format-check, lint, type-check, test)
make check

Pre-commit Hooks

Pre-commit hooks automatically run before each commit. To run them manually:

# Run on all files
make pre-commit-run

# Update hook versions
make pre-commit-update

If you need to bypass hooks temporarily (not recommended):

git commit --no-verify -m "message"

Testing

Running Tests

# Run all tests
make test

# Run with coverage report
make test-cov

# Run specific test file
pytest tests/test_config.py -v

# Run tests matching a pattern
pytest tests/ -k "test_endpoint" -v

Test Structure

  • tests/unit/ - Unit tests for individual components
  • tests/integration/ - Integration tests for multiple components
  • tests/interactive/ - Interactive tests requiring manual verification

Writing Tests

  • Use pytest fixtures for setup/teardown
  • Use appropriate markers: @pytest.mark.unit, @pytest.mark.integration, etc.
  • Aim for >80% code coverage
  • Mock external dependencies (API calls, file system, etc.)

Example:

import pytest
from code_assistant_manager.config import ConfigManager

def test_config_loading(tmp_path):
    """Test configuration file loading."""
    config_file = tmp_path / "providers.json"
    config_file.write_text('{"endpoints": {}}')

    config = ConfigManager(str(config_file))
    assert config.config_data == {"endpoints": {}}

Pull Request Process

Before Submitting

  1. Create a feature branch:

    git checkout -b feature/your-feature-name

  2. Make your changes following code quality standards

  3. Write/update tests for your changes

  4. Run all quality checks:

    make check

  5. Update documentation if needed (README, docstrings, etc.)

  6. Commit your changes:

    git add .
git commit -m "feat: add your feature description"

    Use conventional commit messages:

    • feat: - New feature
    • fix: - Bug fix
    • docs: - Documentation changes
    • test: - Test additions/changes
    • refactor: - Code refactoring
    • style: - Formatting changes
    • chore: - Maintenance tasks

Submitting the PR

  1. Push to your fork:

    git push origin feature/your-feature-name

  2. Open a Pull Request on GitHub with:

    • Clear title and description
    • Reference to related issues (if any)
    • Screenshots/examples (if applicable)
    • Test results confirmation

  3. Address review feedback promptly

  4. Ensure CI passes (when available)

PR Requirements

  • ✅ All tests pass
  • ✅ Code quality checks pass (lint, type-check, format)
  • ✅ New code has tests
  • ✅ Documentation updated
  • ✅ Commit messages are clear and conventional
  • ✅ No merge conflicts with main branch

AI-Assisted Development

This project welcomes AI-assisted contributions. Please follow these additional guidelines when using AI coding assistants:

Guidelines from CLAUDE.md

  1. Always seek approval before git commit and push
  2. Always run tests before completing development of new changes
  3. Always test CLI usages to ensure functionality
  4. After any changes, reinstall the project: 
    rm -rf dist/*
./install.sh uninstall
./install.sh
cp ~/.config/code-assistant-manager/providers.json.bak ~/.config/code-assistant-manager/providers.json

Attribution

When using AI assistance for significant contributions, add attribution in your commit message:

feat: implement new feature

Co-Authored-By: Claude <noreply@anthropic.com>

or for other AI assistants:

feat: implement new feature

AI-Assisted: [Tool Name]

Code Style Guidelines

Python Style

  • Follow PEP 8 (enforced by Flake8)
  • Use type hints where appropriate
  • Maximum line length: 88 characters (Black default)
  • Prefer descriptive variable names over comments
  • Use docstrings for all public functions, classes, and modules

Documentation Style

  • Use Google-style docstrings
  • Include parameter types and return types
  • Provide usage examples for complex functions

Example:

def get_endpoint_config(self, endpoint_name: str) -> Dict[str, str]:
    """
    Get full configuration for an endpoint.

    Args:
        endpoint_name: Name of the endpoint

    Returns:
        Dictionary with endpoint configuration

    Example:
        >>> config.get_endpoint_config("anthropic")
        {'endpoint': 'https://api.anthropic.com', 'api_key_env': 'ANTHROPIC_API_KEY'}
    """
    # implementation

Design Patterns

This project uses industry-standard design patterns. When adding new code:

  • Use Value Objects for validated primitives (see value_objects.py)
  • Use Factory Pattern for creating tools (see factory.py)
  • Use Strategy Pattern for pluggable algorithms (see strategies.py)
  • Use Repository Pattern for data access (see repositories.py)
  • Use Service Layer for business logic (see services.py)

See docs/DESIGN_PATTERNS_README.md for detailed guidance.

Questions or Issues?

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

Thank you for contributing! 🎉