Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
202 lines (147 loc) · 5.48 KB

CONTRIBUTING.md

File metadata and controls

202 lines (147 loc) · 5.48 KB

Contributing to ai-commit-msg

Thank you for taking the time to contribute! This guide will help you get set up and understand the project conventions.

Table of Contents

Code of Conduct

Be respectful and constructive. We welcome contributors of all skill levels.

Getting Started

  1. Fork the repository on GitHub.
  2. Clone your fork locally: 
    git clone https://github.com/<your-username>/ai-commit-msg
cd ai-commit-msg
  3. Add upstream remote: 
    git remote add upstream https://github.com/hidearmoon/ai-commit-msg

Development Setup

Python 3.9+ is required.

# Create and activate a virtual environment (recommended)
python -m venv .venv
source .venv/bin/activate      # Linux/macOS
.venv\Scripts\activate         # Windows

# Install the package in editable mode with dev dependencies
pip install -e ".[dev]"

# Verify the CLI is available
acm --version

Project Structure

ai-commit-msg/
├── src/ai_commit_msg/
│   ├── __init__.py          # Version
│   ├── cli.py               # Click entry point (acm / ai-commit-msg)
│   ├── config.py            # Config loading, merging, persistence
│   ├── git.py               # Git operations + smart diff chunking
│   ├── hook.py              # Git hook install/uninstall
│   ├── prompt.py            # Jinja2 prompt templates + candidate parsing
│   └── providers/
│       ├── __init__.py      # Factory + registry
│       ├── base.py          # Abstract BaseProvider
│       ├── openai.py        # OpenAI provider (also covers DeepSeek)
│       ├── claude.py        # Anthropic Claude provider
│       ├── deepseek.py      # DeepSeek provider
│       └── ollama.py        # Ollama provider
├── tests/
│   ├── conftest.py          # Shared pytest fixtures
│   ├── test_cli.py
│   ├── test_config.py
│   ├── test_git.py
│   ├── test_hook.py
│   ├── test_prompt.py
│   └── test_providers.py
├── pyproject.toml
├── README.md
└── CONTRIBUTING.md

Making Changes

  1. Create a branch off main:

    git checkout -b feat/my-feature

  2. Make your changes. Keep PRs focused — one feature or fix per PR.

  3. Write tests for any new behaviour (see Tests below).

  4. Run the test suite and ensure it passes:

    pytest tests/ -v

  5. Check coverage (aim to keep it above 80%):

    pytest --cov=src --cov-report=term-missing

Adding a new AI provider

  1. Create src/ai_commit_msg/providers/<name>.py implementing BaseProvider.
  2. Register it in src/ai_commit_msg/providers/__init__.py (PROVIDER_NAMES list + registry dict in get_provider).
  3. Add default config in src/ai_commit_msg/config.py (Config dataclass).
  4. Add the provider section to the config CLI in cli.py (config list command).
  5. Write tests in tests/test_providers.py (mock all HTTP calls with pytest-mock).
  6. Document it in README.md.

Tests

We use pytest with pytest-mock for all tests. All HTTP calls to AI providers must be mocked — never make real API calls in tests.

# Run all tests
pytest tests/ -v

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

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

Key conventions:

  • Use mocker.patch (from pytest-mock) to mock httpx.post / httpx.Client calls.
  • Test both the happy path and error paths (ProviderError, GitError, config errors).
  • Use the fixtures in conftest.py for shared setup (temp directories, mock git repos, etc.).

Commit Message Style

This project uses Conventional Commits (naturally, we eat our own dog food):

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

[optional body]
[optional footer]

Types: feat, fix, docs, refactor, test, chore, perf, ci

Examples:

feat(providers): add Gemini provider support
fix(chunking): handle binary files in diff splitting
docs(readme): add Ollama setup instructions
test(config): add coverage for env var override order

Pull Request Guidelines

  • Target the main branch.
  • Fill in the PR template: describe what changed and why.
  • Link any related issues (Closes #123).
  • Keep PRs small and focused. Large PRs are harder to review and slower to merge.
  • All CI checks must pass before merge.
  • A maintainer will review within a few days; please be patient.

Reporting Bugs

Use the Bug Report issue template. Include:

  • Your OS and Python version (python --version)
  • Package version (acm --version)
  • The full command you ran
  • The complete error output
  • Steps to reproduce

Requesting Features

Use the Feature Request issue template. Describe the problem you want solved, not just the solution you have in mind.

Questions?

Open a Discussion or file an issue with the question label.