Skip to content

livery.workshop._versions

livery.workshop._versions

The next version a package's unreleased commits earn.

The release train's version comes from the commit convention the base already enforces (livery.workshop._conventional): the commits since the package's newest receipt tag that touch its directory, each read for a break and a feature. Before 1.0 a break or a feature bumps the minor version and anything else the patch; from 1.0 a break bumps the major, a feature the minor, anything else the patch. A release commit (chore(release)) earns nothing, and a commit whose subject follows no convention counts as a patch.

A package with no receipt tag yet releases at its [release] baseline, else at 0.0.0: the first release is the starting point, not a bump from it.

Functions:

Name Description
baseline

The version package first releases at: its declared baseline, else 0.0.0.

bump

version bumped by the (subject, body) pairs messages, or unchanged.

derive_version

The version package's unreleased commits earn, bare semver.

baseline

baseline(package: Package) -> str

The version package first releases at: its declared baseline, else 0.0.0.

Source code in packages/workshop/src/livery/workshop/_versions.py
def baseline(package: Package) -> str:
    """The version *package* first releases at: its declared baseline, else 0.0.0."""
    contract = load_contract(package.directory / "workshop.toml")
    release = contract.get("release") or {}
    declared = release.get("baseline", "") if isinstance(release, dict) else ""
    return str(declared) or "0.0.0"

bump

bump(version: str, messages: list[tuple[str, str]]) -> str

version bumped by the (subject, body) pairs messages, or unchanged.

Raises:

Type Description
ValueError

when version is not major.minor.patch.

Source code in packages/workshop/src/livery/workshop/_versions.py
def bump(version: str, messages: list[tuple[str, str]]) -> str:
    """*version* bumped by the (subject, body) pairs *messages*, or unchanged.

    Raises:
        ValueError: when *version* is not ``major.minor.patch``.
    """
    major, minor, patch = (int(part) for part in version.split("."))
    counted = [m for m in messages if not _RELEASE_RE.match(m[0])]
    if not counted:
        return version
    breaking = any(
        _BREAK_SUBJECT_RE.match(subject) or _BREAK_FOOTER_RE.search(body)
        for subject, body in counted
    )
    feature = any(_FEATURE_RE.match(subject) for subject, _body in counted)
    if breaking and major >= 1:
        return f"{major + 1}.0.0"
    if breaking or feature:
        return f"{major}.{minor + 1}.0"
    return f"{major}.{minor}.{patch + 1}"

derive_version

derive_version(root: Path, package: Package, *, released: str = '') -> str

The version package's unreleased commits earn, bare semver.

released is the newest receipt's version, read from the tags when empty. With no receipt the answer is the baseline. With one, an answer equal to it means nothing unreleased touches the package, which the caller reports.

Source code in packages/workshop/src/livery/workshop/_versions.py
def derive_version(root: Path, package: Package, *, released: str = "") -> str:
    """The version *package*'s unreleased commits earn, bare semver.

    *released* is the newest receipt's version, read from the tags
    when empty. With no receipt the answer is the baseline. With one,
    an answer equal to it means nothing unreleased touches the
    package, which the caller reports.
    """
    if not released:
        from livery.workshop._update import latest_released

        released = latest_released(git.tags(root)).get(package.path, "")
    if not released:
        return baseline(package)
    tag = f"{package.path}/v{released}"
    log = git.run(
        root,
        "log",
        f"--format=%s{_FIELD}%b{_RECORD}",
        f"{tag}..HEAD",
        "--",
        package.path,
    )
    messages: list[tuple[str, str]] = []
    for record in log.split(_RECORD):
        if not record.strip():
            continue
        subject, _, body = record.strip("\n").partition(_FIELD)
        messages.append((subject, body))
    return bump(released, messages)