Skip to content

AGENTS.md

Latest commit

 

History

History
71 lines (43 loc) · 3.38 KB

AGENTS.md

File metadata and controls

71 lines (43 loc) · 3.38 KB

Agent instructions

This file provides guidance to AI Agents when working with code in this repository.

Commands

Add --agent-digest=term -p no:sugar to all pytest commands to provide optimized output.

# Install for development
uv sync --all-groups

# Run all tests
uv run pytest --agent-digest=term -p no:sugar

# Run a single test file
uv run pytest --agent-digest=term -p no:sugar tests/test_files.py

# Run a single test
uv run pytest --agent-digest=term -p no:sugar tests/test_files.py::test_function_name

# Lint and format
uv run ruff check bumpversion/
uv run ruff format bumpversion/

# Type checking
uv run mypy bumpversion/

# Check docstring coverage (must stay above 95%)
uv run interrogate bumpversion/

# Run pre-commit hooks on all files
pre-commit run --all-files

Architecture

The tool works as a pipeline: read config → detect SCM state → parse current version → run setup hooks → calculate next version → build context → modify files → run pre-commit hooks → commit & tag → run post-commit hooks.

Key modules

bumpversion/cli.py — Click-based CLI entry point. Commands: bump, show, replace, sample-config, show-bump. Routes to bump.py or show.py for logic.

bumpversion/bump.py — Core workflow: get_next_version() and do_bump(). Orchestrates config loading, file modification, and SCM operations.

bumpversion/config/ — Pydantic 2.x models for configuration. files.py discovers and reads config from pyproject.toml, .bumpversion.toml, setup.cfg, etc. models.py defines BumpVersionConfig and FileChange.

bumpversion/versioning/ — Version parsing and manipulation. models.py has Version, VersionComponent, VersionComponentSpec. functions.py has NumericFunction, ValuesFunction, CalVerFunction. serialization.py handles template-based version string rendering.

bumpversion/files.py — ConfiguredFile performs search/replace on individual files. modify_files() handles batches with dry-run support. Supports glob patterns, data files (JSON/YAML/TOML with key paths).

bumpversion/scm/ — Git (git.py) and Mercurial (hg.py) backends. Reads current version from tags, creates commits and tags. Supports moveable tags and commit signing.

bumpversion/context.py — Builds the template context dict injected into version format strings (datetime, SCM info, environment variables).

bumpversion/hooks.py — Runs setup/pre-commit/post-commit shell hooks with version info as environment variables.

Configuration model

Config flows from file (.bumpversion.toml or [tool.bumpversion] in pyproject.toml) → CLI overrides → resolved BumpVersionConfig. The current_version field is the source of truth; it's updated in-place in config files as part of each bump.

Version components

Each part of a version (major, minor, patch) is a VersionComponent with a VersionComponentSpec describing its behavior (numeric increment, fixed values list, or CalVer expression). Components have dependency relationships — bumping a higher-order component resets dependent ones.

Code style

  • Line length: 119 characters
  • Docstrings: Google style, required on all public symbols (95% coverage enforced by interrogate)
  • Ruff with preview mode enabled; see [tool.ruff.lint] in pyproject.toml for full rule set
  • Type annotations required on all function signatures