incremental

Incremental is a version-management tool for Python projects that follows the CalVer (calendar versioning) scheme of YY.MM.PATCH. Instead of hand-editing version strings, it stores your project’s version in a generated _version.py module and updates it through an incremental update command.

Beyond bumping numbers, Incremental resolves “indeterminate” version references such as “YourProject NEXT” throughout your codebase, so documentation and code can point at the upcoming release before it ships. It integrates with setuptools and hatch as a build-time plugin and exposes a Version object your code can import.

What You Get

• An incremental update CLI for bumping versions with --rc and --patch support
• A generated _version.py holding your project’s canonical version
• Automatic resolution of “NEXT” indeterminate versions across the codebase
• Build-backend integration for setuptools and hatch
• An importable Version object with CalVer semantics

Common Use Cases

• Managing CalVer version numbers for a Python package without manual edits
• Automating release and release-candidate bumps in CI
• Referencing an upcoming release in docs via NEXT placeholders
• Exposing a structured version object to application code

Under The Hood

Architecture - Incremental lives under src/incremental/ with a compact design: __init__.py defines the Version value type and comparison logic, update.py implements the incremental update command that rewrites _version.py and resolves NEXT references, and _hatch.py provides the hatch build-backend hook (with setuptools support wired through pyproject.toml). Version state is persisted in a generated per-project _version.py.

Tech Stack - Pure Python 3, fully type-annotated (ships py.typed), packaged via pyproject.toml, with mypy config and a tox-driven test matrix. Separate pinned requirement files cover linting, typing, and tests. It integrates with setuptools and hatch build backends.

Code Quality - A mature, small, and stable project maintained under the Twisted organization, with a dedicated tests/ package and enforced typing/linting. Release cadence is infrequent because the tool is essentially feature-complete, and the codebase is tidy and single-purpose.

API Design - Developer experience is straightforward: add Incremental as a build dependency, run incremental update to manage the version, and import Version where needed. The CLI flags map cleanly to release/RC/patch intent, and the NEXT-resolution feature is a distinctive convenience with minimal configuration.