Skip to content

livery.extensions.changelog._cliff

livery.extensions.changelog._cliff

The changelog extension's engine: git-cliff, driven per package.

Each package carries a cliff.toml, the extension's per-package content, which states its tag line, its paths, and the entry's shape. This module runs git-cliff against that config for the entry the commits since the last release earn, and NOTES, the extension's answer to the workshop's release-notes query, writes it into the package's CHANGELOG.md. The next version is not git-cliff's: the workshop derives it from the same commits.

Classes:

Name Description
CliffChangelog

Release notes as git-cliff entries in each package's CHANGELOG.md.

Functions:

Name Description
credit_is_reachable

Whether a credential is in reach to ask the forge who wrote what.

config_path

package's changelog contract, or fail naming what to render.

unreleased_entry

The changelog entry for what is unreleased in package.

notes

Answer the release-notes query about the workspace at root with NOTES.

Attributes:

Name Type Description
CONFIG_NAME
TOKEN_VARIABLE
NOTES

CONFIG_NAME module-attribute

CONFIG_NAME = 'cliff.toml'

TOKEN_VARIABLE module-attribute

TOKEN_VARIABLE = {'github': 'GITHUB_TOKEN', 'gitea': 'GITEA_TOKEN', 'gitlab': 'GITLAB_TOKEN'}

NOTES module-attribute

NOTES = CliffChangelog()

CliffChangelog

Release notes as git-cliff entries in each package's CHANGELOG.md.

The extension's livery.workshop.ReleaseNotes provider: the entry is git-cliff's, through the package's cliff.toml; the history is the package's CHANGELOG.md, created at the first record, newest entry first.

Methods:

Name Description
entry

The entry git-cliff writes for what is unreleased in package.

record

Write version's entry at the top of CHANGELOG.md.

verify

A missing ## <version> entry in CHANGELOG.md, or nothing.

entry

entry(root: Path, package: Package, version: str = '') -> str

The entry git-cliff writes for what is unreleased in package.

Source code in packages/extensions/changelog/src/livery/extensions/changelog/_cliff.py
def entry(self, root: Path, package: Package, version: str = "") -> str:
    """The entry git-cliff writes for what is unreleased in *package*."""
    return unreleased_entry(root, package, version)

record

record(package: Package, version: str, entry: str) -> list[str]

Write version's entry at the top of CHANGELOG.md.

An entry already under version's heading is replaced when a new one is given: the stranded shape, a heading whose tag never cut, regenerates rather than under-documenting what ships.

Source code in packages/extensions/changelog/src/livery/extensions/changelog/_cliff.py
def record(self, package: Package, version: str, entry: str) -> list[str]:
    """Write *version*'s *entry* at the top of ``CHANGELOG.md``.

    An entry already under *version*'s heading is replaced when a
    new one is given: the stranded shape, a heading whose tag never
    cut, regenerates rather than under-documenting what ships.
    """
    changelog = package.directory / "CHANGELOG.md"
    text = changelog.read_text("utf-8") if changelog.is_file() else "# Changelog\n"
    if f"## {version}" not in text and f"## [{version}]" not in text:
        # A blank line on each side, so the new entry and the one it
        # sits above stay separate blocks.
        insert = "\n" + (entry or f"## [{version}]\n\n-").strip() + "\n"
        first_entry = text.find("\n## ")
        if first_entry == -1:
            text = text.rstrip("\n") + "\n" + insert
        else:
            text = text[:first_entry] + insert + text[first_entry:]
        changelog.write_text(text, encoding="utf-8")
        return ["CHANGELOG.md (review the entry before tagging)"]
    if entry:
        rewritten = _replace_entry(text, version, entry)
        if rewritten != text:
            changelog.write_text(rewritten, encoding="utf-8")
            return ["CHANGELOG.md (the stranded entry regenerated; review it)"]
    return []

verify

verify(package: Package, version: str) -> list[str]

A missing ## <version> entry in CHANGELOG.md, or nothing.

Source code in packages/extensions/changelog/src/livery/extensions/changelog/_cliff.py
def verify(self, package: Package, version: str) -> list[str]:
    """A missing ``## <version>`` entry in ``CHANGELOG.md``, or nothing."""
    changelog = package.directory / "CHANGELOG.md"
    body = changelog.read_text("utf-8") if changelog.is_file() else ""
    if f"## {version}" in body or f"## [{version}]" in body:
        return []
    return [f"CHANGELOG.md has no '## {version}' entry"]

credit_is_reachable

credit_is_reachable(root: Path) -> bool

Whether a credential is in reach to ask the forge who wrote what.

The changelog names authors by asking the forge, which a private repository answers only for a caller it can authenticate. Without the credential git-cliff stops rather than degrading, so the caller runs it offline instead.

Source code in packages/extensions/changelog/src/livery/extensions/changelog/_cliff.py
def credit_is_reachable(root: Path) -> bool:
    """Whether a credential is in reach to ask the forge who wrote what.

    The changelog names authors by asking the forge, which a private
    repository answers only for a caller it can authenticate. Without
    the credential git-cliff stops rather than degrading, so the
    caller runs it offline instead.
    """
    return bool(_credential(root)[1])

config_path

config_path(package: Package) -> Path

package's changelog contract, or fail naming what to render.

Source code in packages/extensions/changelog/src/livery/extensions/changelog/_cliff.py
def config_path(package: Package) -> Path:
    """*package*'s changelog contract, or fail naming what to render."""
    path = package.directory / CONFIG_NAME
    if not path.is_file():
        fail(
            f"{package.path} has no {CONFIG_NAME}:"
            f" run `{footman.prog()} sync`, which composes it from the changelog"
            " extension's fragment"
        )
    return path

unreleased_entry

unreleased_entry(root: Path, package: Package, version: str = '') -> str

The changelog entry for what is unreleased in package.

With version, the entry is headed by it and dated today, and credits its authors where a credential is in reach. Without one it is headed ## [Unreleased], which is what a dev build's excerpt wants, and credits no one: nobody credits a dev build's authors, and the lookup pages through every pull request the forge holds, once per package, against the forge's API budget. Empty when no commit touches the package.

Source code in packages/extensions/changelog/src/livery/extensions/changelog/_cliff.py
def unreleased_entry(root: Path, package: Package, version: str = "") -> str:
    """The changelog entry for what is unreleased in *package*.

    With *version*, the entry is headed by it and dated today, and
    credits its authors where a credential is in reach. Without one it
    is headed ``## [Unreleased]``, which is what a dev build's excerpt
    wants, and credits no one: nobody credits a dev build's authors,
    and the lookup pages through every pull request the forge holds,
    once per package, against the forge's API budget. Empty when no
    commit touches the package.
    """
    args = ["--unreleased", "--strip", "all"]
    if version:
        args += ["--tag", f"packages/{package.member}/v{version}"]
    return _run(root, package, *args, offline=not version).strip()

notes

notes(root: Path) -> ReleaseNotes

Answer the release-notes query about the workspace at root with NOTES.

Source code in packages/extensions/changelog/src/livery/extensions/changelog/_cliff.py
def notes(root: Path) -> ReleaseNotes:
    """Answer the ``release-notes`` query about the workspace at *root* with `NOTES`."""
    del root
    return NOTES