Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
373 lines (260 loc) · 7.96 KB

CONTRIBUTING.md

File metadata and controls

373 lines (260 loc) · 7.96 KB
Raw

Contributing to A2A

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

📋 Table of Contents

Code of Conduct

By participating in this project, you agree to abide by our Code of Conduct. Please read it before contributing.

Getting Started

  1. Fork the repository on GitHub

  2. Clone your fork locally:

    git clone https://github.com/YOUR-USERNAME/a2a.git
cd a2a

  3. Add the upstream remote:

    git remote add upstream https://github.com/H2OKing89/a2a.git

Development Setup

Prerequisites

  • Python 3.11 or higher
  • mediainfo system package
  • Git

Environment Setup

  1. Create a virtual environment:

    python -m venv .venv
source .venv/bin/activate  # Linux/macOS

  2. Install dependencies:

    make install-dev

  3. Install pre-commit hooks:

    make setup-hooks

  4. Verify your setup:

    make test

Making Changes

Branch Naming Convention

Use descriptive branch names:

  • feature/add-new-command - New features
  • fix/resolve-cache-issue - Bug fixes
  • docs/update-readme - Documentation
  • refactor/simplify-client - Code refactoring
  • test/add-quality-tests - Test additions

Commit Messages

Follow Conventional Commits:

<type>(<scope>): <description>

[optional body]

[optional footer]

Types:

  • feat: New feature
  • fix: Bug fix
  • docs: Documentation changes
  • style: Code style changes (formatting, etc.)
  • refactor: Code refactoring
  • test: Adding or modifying tests
  • chore: Maintenance tasks

Examples:

feat(quality): add support for FLAC format analysis
fix(audible): handle rate limiting gracefully
docs(readme): add installation instructions for Windows
test(abs): add integration tests for library endpoints

Code Style

Python Style Guide

Running Formatters

# Format all code
make format

# Check formatting without changes
black --check src/ tests/ cli.py
isort --check-only src/ tests/ cli.py

Linting

# Run all linters
make lint

This runs:

  • flake8 - Style guide enforcement
  • mypy - Type checking
  • bandit - Security analysis

Pydantic Models

When creating Pydantic models for API responses:

from pydantic import BaseModel, Field

class MyModel(BaseModel):
    """Model description."""

    my_field: str = Field(alias="myField")
    optional_field: str | None = None

    model_config = {"extra": "ignore"}

Type Hints

Type hints are encouraged but not strictly required:

def analyze_quality(items: list[LibraryItem]) -> QualityReport:
    """Analyze quality of library items."""
    ...

Testing

Running Tests

# Run all tests
make test

# Run with coverage
make coverage

# Run specific tests
pytest tests/test_quality_analyzer.py
pytest -k "test_cache"

# Run with verbose output
pytest -v

Writing Tests

  • Place tests in the tests/ directory
  • Name test files test_*.py
  • Name test functions test_*
  • Use pytest fixtures from conftest.py

Example test:

import pytest
from src.quality.analyzer import QualityAnalyzer

class TestQualityAnalyzer:
    """Tests for QualityAnalyzer."""

    def test_analyze_high_bitrate(self, mock_abs_client):
        """Test that high bitrate items are marked excellent."""
        analyzer = QualityAnalyzer(mock_abs_client)
        result = analyzer.analyze(item_with_high_bitrate)
        assert result.tier == "EXCELLENT"

Test Coverage

Aim for meaningful test coverage:

  • Cover happy paths and error cases
  • Test edge cases
  • Mock external dependencies (APIs, file system)

Pull Request Process

Before Submitting

  1. Update your branch:

    git fetch upstream
git rebase upstream/main

  2. Run all checks:

    make pre-commit
make test

  3. Update documentation if needed

Submitting a PR

  1. Push your changes to your fork
  2. Open a Pull Request against main
  3. Fill out the PR template completely
  4. Link any related issues

PR Requirements

  • All CI checks pass
  • Tests added for new functionality
  • Documentation updated if needed
  • Code follows project style guide
  • Commits follow conventional commits format
  • CHANGELOG.md updated with your changes
  • Version bumped if needed (see Versioning below)

Review Process

  1. A maintainer will review your PR
  2. Address any requested changes
  3. Once approved, the PR will be merged

Versioning

A2A follows Semantic Versioning: MAJOR.MINOR.PATCH

When to Bump Version

PATCH (0.1.0 → 0.1.1): Backward-compatible bug fixes only

  • Fixing a crash
  • Correcting error messages
  • Performance improvements (no API changes)

MINOR (0.1.0 → 0.2.0): New features that are backward-compatible

  • Adding new CLI flags (e.g., --fast)
  • Adding new API methods
  • Adding new models/classes
  • Bug fixes + new features together

MAJOR (0.1.0 → 1.0.0): Breaking changes

  • Removing CLI commands or flags
  • Changing API signatures
  • Changing config file structure
  • Removing or renaming public classes/functions

How to Bump Version

# Using the version utility
python tools/version.py patch  # 0.1.0 → 0.1.1
python tools/version.py minor  # 0.1.0 → 0.2.0
python tools/version.py major  # 0.1.0 → 1.0.0

# Or using make
make bump-patch
make bump-minor
make bump-major

Version is stored in src/__init__.py:

__version__ = "0.2.0"

Updating CHANGELOG.md

When your PR adds features or fixes bugs, update CHANGELOG.md:

  1. Add an entry under the [Unreleased] section if version hasn't been bumped yet
  2. Or create a new version section if bumping version (e.g., ## [0.2.0] - 2025-12-28)
  3. Organize changes by category:
    • ### Added - New features
    • ### Fixed - Bug fixes
    • ### Changed - Changes to existing functionality
    • ### Deprecated - Soon-to-be removed features
    • ### Removed - Removed features
    • ### Security - Security fixes
    • ### Performance - Performance improvements

Example:

## [0.2.0] - 2025-12-28

### Added
- Async batch enrichment service for Audible quality discovery
- New CLI flag `--fast` for `quality upgrades` to skip license requests

### Fixed
- Missing Audible pricing in `quality upgrades`
- Progress bar stuck at 0% during async batch enrichment

### Performance
- Concurrent async quality discovery with configurable limits

Reporting Issues

Bug Reports

When reporting bugs, please include:

  • Environment: OS, Python version
  • Steps to reproduce
  • Expected behavior
  • Actual behavior
  • Error messages/logs
  • Configuration (sanitized)

Use the bug report template.

Feature Requests

When requesting features, please include:

  • Use case: Why do you need this?
  • Proposed solution: How should it work?
  • Alternatives considered: Other approaches you've thought of

Use the feature request template.

Questions?

Thank you for contributing! 🎧