semver-dredd

Semantic-versioning workflow for public APIs.

semver-dredd compares a saved API snapshot with the current source tree, classifies the change as NONE, PATCH, MINOR, or BREAKING, and helps you write or suggest the next version.

What it is

• Core engine for snapshot loading, diffing, version math, and config resolution.
• Plugin-based API inspection for different languages and source models.
• CLI workflow for initializing a project, checking API drift, baking a new release baseline, generating standalone snapshots, and inspecting plugins.
• Programmatic Python API for direct use in tests, release automation, or custom tooling.

Officially documented plugin keys:

• python
• go
• java
• javaparser
• bundle (built into core for VERSION-file dependency bundles)

What it does

semver-dredd supports:

• config-driven workflows via .semver.yaml
• .env / environment / CLI override precedence
• multi-document config candidate fallback
• plugin-specific include / exclude scope forwarding
• machine-readable plugin inventory via plugin list --json|--yaml
• plugin metadata and generator provenance in plugin snapshots
• pathless status, bake, and snapshot when source.path is configured

Install

# Core package only
pip install semver-dredd

# Core package + official extras
pip install "semver-dredd[python]"
pip install "semver-dredd[go]"
pip install "semver-dredd[java]"
pip install "semver-dredd[javaparser]"
pip install "semver-dredd[all]"

# Or install plugin packages directly
pip install python-3.10-dredd
pip install go-1.20-dredd
pip install java-1.8-dredd
pip install javaparser-1.8-dredd

# Or install the official meta-package
pip install semver-dredd-all

Extras work by depending on separately published plugin distributions. For example, semver-dredd[python] resolves the python-3.10-dredd package from PyPI and then discovers it through the semver_dredd.plugins entry-point group.

Development install:

poetry install --with dev
poetry run pip install -e plugins/python-3.10-dredd
poetry run pip install -e plugins/go-1.20-dredd
poetry run pip install -e plugins/java-1.8-dredd
poetry run pip install -e plugins/javaparser-1.8-dredd

Publish to PyPI

Use the local Twine-based publish helper to build, validate, and upload the core package plus the separately installable official plugins that power extras.

# Build + twine-check everything without uploading
bash scripts/publish_pypi.sh --check-only

# Upload plugins first, then core, then the meta-package
TWINE_USERNAME=__token__ \
TWINE_PASSWORD=pypi-... \
bash scripts/publish_pypi.sh

Useful flags:

# Skip parts that are already published
bash scripts/publish_pypi.sh --skip-plugins
bash scripts/publish_pypi.sh --skip-core
bash scripts/publish_pypi.sh --skip-meta

# Target a custom repository / TestPyPI
bash scripts/publish_pypi.sh --repository testpypi
bash scripts/publish_pypi.sh --repository-url https://test.pypi.org/legacy/

# Resume after a partial upload failure
bash scripts/publish_pypi.sh --start-from javaparser-1.8-dredd --skip-existing

The helper publishes official plugin packages before the core package so that extras such as semver-dredd[python] can resolve from PyPI as soon as the core release becomes available.

If PyPI rate-limits an upload with HTTP 429, wait a bit and rerun the helper from the failed package with --start-from ... --skip-existing. Add --verbose when you need Twine to show the underlying retry details.

Run it

Typical first-run workflow:

semver-dredd plugin list
semver-dredd init . --plugin python --version 1.0.0
semver-dredd status --details
semver-dredd bake

Plugin inspection lives under the plugin command group. The supported inventory command is semver-dredd plugin list (there is no top-level semver-dredd list alias).

The important workflow rule is:

• init requires an explicit --plugin
• later commands can use .semver.yaml defaults
• CLI arguments override environment, which overrides config

Language examples:

# Python
semver-dredd init mypackage --plugin python --version 1.0.0
semver-dredd status --details

# Go
semver-dredd init ./pkg/api --plugin go --version 1.0.0
semver-dredd status ./pkg/api --plugin go --details

# Java (regex parser)
semver-dredd init ./src/main/java --plugin java --version 1.0.0

# JavaParser (AST parser)
semver-dredd init ./src/main/java --plugin javaparser --version 1.0.0

For full command reference and common workflows, see USAGE.md.

Configuration

The main project config is .semver.yaml.

• Generate a commented template with semver-dredd template
• See a full, worked example in example/semver_showcase.yaml
• See the config/schema reference in SCHEMA.md
• Environment variables (SEMVER_DREDD_*) and the full precedence order (config < .env < environment < CLI) are documented in USAGE.md

Managed files typically include:

File	Purpose
.semver.yaml	project configuration
baked.yaml	release baseline snapshot
current.yaml	latest generated snapshot
VERSION	current version string

Extend or patch it

• Plugin authoring guide: HOWTO.md
• Snapshot/config schema reference: SCHEMA.md
• Example plugins: plugins/
• Demos and example configs: example/

Useful development commands:

poetry run pytest -v
poetry run python -m cli --help
bash example/demo_python.sh
bash scripts/smoke.sh python unit

Programmatic API

from semverdredd import compare_and_suggest

result, suggested = compare_and_suggest(
    "old_module",
    "new_module",
    plugin_name="python",
    current_version="1.2.0",
)

print(result.change_kind.name)
print(suggested)

The CLI/docs cover the primary user workflow; the importable API is best suited for automation and tests.