Skip to content

AGENTS.md

Latest commit

 

History

History
62 lines (45 loc) · 4.26 KB

AGENTS.md

File metadata and controls

62 lines (45 loc) · 4.26 KB

AGENTS instructions

Purpose

This file is the auto-loaded entry point for AI agents working on the commitizen repository. It holds the rules an agent needs in every session. Deeper guidance lives in:

Follow these instructions in addition to any higher-level tool or system rules.

Project at a glance

  • Project: commitizen — Python CLI for enforcing Conventional Commits, automating version bumps, and generating changelogs.
  • Library + CLI: code is reachable both via cz and import commitizen.
  • Cross-platform: tests run on Linux/macOS/Windows × Python 3.10–3.14. Avoid POSIX-only assumptions (paths, subprocesses, line endings).
  • Key entrypoints:
    • commitizen/cli.py — CLI definition (decli + argparse).
    • commitizen/commands/ — one module per cz subcommand.
    • commitizen/config/ — configuration discovery and parsing.
    • commitizen/providers/ — version providers.
    • commitizen/changelog_formats/ — changelog file formats.

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/providers/, 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)

For recurring task types (add a provider, deprecate an API, regenerate snapshots, ...), use the matching playbook in For AI Agents § Playbooks instead of reinventing the workflow.

Do not touch

These files are regenerated by Commitizen-specific tooling, so hand-edits get reverted on the next release or doc rebuild:

  • CHANGELOG.md — produced by cz changelog. Hand-edits will be overwritten on the next release.
  • commitizen/__version__.py — bumped by cz bump via the configured version provider.
  • .pre-commit-config.yaml:rev: lines under the Commitizen repo — bumped by cz bump (version_files in pyproject.toml).
  • docs/images/cli_help/*.svg and docs/images/cli_interactive/*.gif — regenerated by uv run poe doc:screenshots. See the update-snapshots playbook.
  • tests/**/* snapshot files used by pytest-regressions — regenerated via uv run poe test:regen.

Mandatory PR reminders

These are easy to miss when working from an agent and are required by the PR template:

  1. Complete the AI disclosure. Check "Was generative AI tooling used to co-author this PR?" and fill in the Generated-by: trailer with the tool name. Details: Pull Request Guidelines § AI-Assisted Contributions.
  2. Run uv run poe all before pushing. This is the command named in the PR template; it auto-formats then runs the same lint/check/test pipeline as CI. To mirror CI exactly afterwards, run uv run poe ci (uses prek, does not auto-format).
  3. Fill in "Steps to Test This Pull Request" with the exact commands you ran locally — the maintainers re-run them.

When unsure

When behavior is ambiguous, assume backward compatibility with current tests and docs is required. Add a deprecation window instead of breaking it; see the deprecate-public-api playbook.