Skip to content

AGENTS.md

Latest commit

 

History

History
115 lines (80 loc) · 6.3 KB

AGENTS.md

File metadata and controls

115 lines (80 loc) · 6.3 KB
Raw

AGENTS instructions

Purpose

This file provides project-specific guidance for AI agents (and other automated tools) working on the commitizen repository. Follow these instructions in addition to any higher-level system or tool rules.

Project Overview

  • Project: commitizen - a tool to help enforce and automate conventional commits, version bumps, and changelog generation.
  • Primary language: Python (library + CLI).
  • Cross-platform: Tests run on Linux, macOS, and Windows. Avoid POSIX-only assumptions in code (paths, subprocesses, line endings).
  • Key entrypoints:
    • commitizen/cli.py - main CLI implementation.
    • commitizen/commands/ - subcommands such as bump, commit, changelog, check, etc.
    • commitizen/config/ - configuration discovery and loading.
    • commitizen/providers/ - version providers (e.g., pep621, poetry, npm, uv).
  • Config sources: pyproject.toml (project config, poe tasks, ruff, mypy), .pre-commit-config.yaml (hooks), .github/workflows/ (CI).

General Expectations

  • Preserve public behavior and CLI UX — no breaking changes to APIs, CLI flags, or exit codes unless explicitly requested.
  • Update or add tests/docs when you change user-facing behavior.
  • Commit messages must follow Conventional Commits (enforced by commitizen itself).
  • Pull requests must follow the Pull Request Guidelines and the template in .github/pull_request_template.md.

Setup and Validation

Full contributor guidelines (prerequisites, workflow, PR process): docs/contributing/contributing.md.

Bootstrap

uv sync --frozen --group base --group test --group linters
uv run poe setup-pre-commit   # install git hooks (uses prek, a pre-commit runner)

Local commands

  • Format: uv run poe format (runs ruff check --fix then ruff format)
  • Lint: uv run poe lint (runs ruff check then mypy)
  • Test: uv run poe test (runs pytest -n auto)
  • CI-equivalent: uv run poe ci (commit check + pre-commit hooks via prek + test with coverage)
  • Full local check: uv run poe all (format + lint + check-commit + coverage)

Always run at least uv run ruff check --fix . && uv run ruff format . before pushing. CI will fail if the formatter modifies any files.

CI pipeline

  • CI runs poe ci on a matrix of Python 3.10–3.14 × ubuntu/macos/windows.
  • Pre-commit hooks are defined in .pre-commit-config.yaml and run via prek (a pre-commit compatible runner).
  • The matrix is fail-fast: inspect the earliest failing job that completed; others are cancelled.

Common CI failure patterns

  • "Format Python code...Failed": Run uv run poe format and commit the result.
  • mypy [arg-type] on TypedDict: Dynamically-constructed dicts (e.g., from pytest.mark.parametrize) passed to TypedDict-typed params need # type: ignore[arg-type].
  • "pathspec 'vX.Y.Z' did not match": .pre-commit-config.yaml pins a tag of this repo. Rebase onto master to pick up the tag.
  • VersionProtocol + issubclass: This Protocol has non-method members (properties), so issubclass() raises TypeError. Use hasattr checks for runtime validation.

What to Read Before Changing

Changing... Read first
CLI flags/arguments commitizen/cli.py, docs/commands/<cmd>.md, tests/test_cli/
Bump logic commitizen/bump.py, commitizen/commands/bump.py, docs/commands/bump.md
Changelog generation commitizen/changelog.py, commitizen/changelog_formats/, docs/commands/changelog.md
Version schemes commitizen/version_schemes.py, tests/test_version_schemes.py
Version providers commitizen/providers/, tests/test_providers.py, docs/config/version_provider.md
Config resolution commitizen/config/, tests/test_conf.py, docs/config/
Tag handling commitizen/tags.py, tests/test_tags.py
Pre-commit / CI .pre-commit-config.yaml, .github/workflows/, pyproject.toml (poe tasks)

Coding Guidelines

  • Types: Preserve or improve existing type hints.
  • Errors: Prefer commitizen/exceptions.py error types; keep messages clear for CLI users.
  • Output: Use commitizen/out.py; do not add noisy logging.
  • Testing: Follow the Arrange, Act, Assert (AAA) pattern. Visually separate these phases with blank lines or comments.

When Unsure

  • Prefer reading tests and documentation first to understand the expected behavior.
  • When behavior is ambiguous, assume backward compatibility with current tests and docs is required.

Documentation Guidelines

  • 100% Coverage: Every new module, class, method, and function MUST have a docstring. No exceptions
  • Even simple functions or internal helpers require documentation to explain their context

Docstring Format: Modified Google Style

Use Google Docstring Style with these major modifications:

  1. NEVER include type hints in the docstring. We rely exclusively on Python's PEP 484 type signatures.
  2. Classes MUST include an example. Any class documentation must contain a brief usage example formatted in Markdown.
  3. Class Attributes MUST be documented. The class docstring must document the instance variables initialized in __init__ within an Attributes: section.

Format Rules:

  • Args:, Returns:, and Attributes: sections must describe the semantic meaning and constraints of the variables, not their types.
  • Omit the type in the lists (e.g., use user_id: The ID of the user, NOT user_id (int): The ID of the user).

Content Focus: The "What" and "Why"

Code explains how. Your docstrings must explain what and why.

When documenting, you may include:

  1. The Core Intent What business or technical rule is this solving?
  2. Considerations: Architectural choices. Why was this approach chosen over the obvious alternative? Why the complexity (if introduced)?
  3. Discarded Approaches: If a simpler method wasn't used (e.g., avoiding an ORM feature for raw SQL, or caching strategies), explain what was discarded and why.
  4. Edge Cases & Gotchas: What weird scenarios does this code handle?

In the end, the reader must understand the intention behind the decisions, to avoid making the same mistakes.