Contributing Guide¶

Thank you for your interest in contributing to CCG! This guide will help you get started.

Quick Start¶

Fork and clone the repository
Set up environment: ./scripts/setup_venv.sh
Install pre-commit: pre-commit install
Create branch: git checkout -b feat/my-feature
Make changes and add tests
Test across versions: ./scripts/tox-mise.sh
Commit and Push with CCG: ccg

Development Setup¶

Automated Setup (Recommended)¶

# Clone your fork
git clone https://github.com/YOUR_USERNAME/conventional-commits-generator.git
cd conventional-commits-generator

# Run automated setup
./scripts/setup_venv.sh

# Activate environment
source .venv/bin/activate

Install Pre-commit Hooks¶

Pre-commit hooks ensure code quality before commits:

# Install hooks
pre-commit install

# Test hooks
pre-commit run --all-files

The hooks will check for:

Trailing whitespace
File endings
TOML/YAML syntax
Debug statements
Large files

Development Workflow¶

1. Make Changes¶

# Create feature branch
git checkout -b feat/new-feature

# Edit code
vim src/ccg/module.py

# Add tests
vim tests/unit/test_module.py

2. Run Tests¶

# Quick test with current Python version
pytest

# Test across all supported versions (3.9-3.13)
./scripts/tox-mise.sh

# Test specific version
./scripts/tox-mise.sh -e py312

# Test in parallel (faster)
./scripts/tox-mise.sh -p auto

3. Create Commit¶

Use CCG to create conventional commits:

# Commit and Push with CCG
ccg

# Follow the interactive prompts

4. Submit PR¶

# Create PR on GitHub
# Use conventional commit format in PR title
# Example: "feat(cli): add verbose output flag"

Code Standards¶

Style Guidelines¶

Type Hints: Required for all functions
Docstrings: Google Style for public functions
Line Length: Maximum 100 characters
Formatting: Use f-strings for string formatting
Coverage: 100% test coverage required

Docstring Example¶

def validate_commit_message(message: str) -> tuple[bool, str]:
    """Validate a commit message against Conventional Commits specification.

    Args:
        message: The commit message to validate.

    Returns:
        A tuple containing validation status and error message:
        - bool: True if valid, False otherwise
        - str: Error message if invalid, empty string if valid

    Examples:
        >>> validate_commit_message("feat: add feature")
        (True, "")
        >>> validate_commit_message("invalid")
        (False, "Invalid format")
    """
    # Implementation...

Learn more: Google Python Style Guide - Docstrings

Testing Requirements¶

Coverage¶

All code must maintain 100% test coverage:

# Run tests with coverage
pytest

# View coverage report
pytest --cov-report=html

Multi-version Testing¶

Test across all supported Python versions:

# Test all versions
./scripts/tox-mise.sh

# The script handles:
# - mise installation (if needed)
# - tox installation (if needed)
# - Python 3.9-3.13 installation (if needed)
# - Running tests across all versions

Type Checking¶

# Run mypy type checker
mypy src/ccg

# Or via tox
./scripts/tox-mise.sh -e mypy

Pull Request Process¶

Before Submitting¶

Run full test suite:

./scripts/tox-mise.sh
pre-commit run --all-files
mypy src/ccg

Update documentation if needed
Ensure 100% coverage maintained

PR Guidelines¶

Title: Use conventional commit format

feat(cli): add support for custom templates

Description: Include:

What changed
Why it changed
How to test
Related issues

Checklist:

Project Structure¶

src/ccg/
├── __init__.py      # Version and exports
├── cli.py           # CLI interface and orchestration
├── core.py          # Commit generation logic
├── git.py           # Git operations
├── utils.py         # UI utilities and formatting
└── config.py        # Configuration

tests/               # tests (100% coverage)
scripts/             # Development scripts
docs/                # MkDocs documentation