Skip to content

livery.workshop._release_notes

livery.workshop._release_notes

Release notes: the one-answer query the release train writes notes through.

A release stamps a version, and a package's history says what the version holds. The train never writes that history itself: it asks the provider the listed extensions answer the release-notes query with for the entry the unreleased commits earn, has the provider record it, and has it judge the recorded notes before a tag is cut. A workspace whose extensions answer nothing releases without notes, and the train says so where it would have written them.

One answer at a time: the query combines by nearest, so two listed extensions answering, neither requiring the other, refuse naming both.

Classes:

Name Description
ReleaseNotes

What a release-notes provider answers.

Functions:

Name Description
release_notes

The provider the extensions listed at root answer; None when none answers.

Attributes:

Name Type Description
RELEASE_NOTES Query[ReleaseNotes | None]
NO_PROVIDER

RELEASE_NOTES module-attribute

RELEASE_NOTES: Query[ReleaseNotes | None] = Query('release-notes')

NO_PROVIDER module-attribute

NO_PROVIDER = 'no release notes: no listed extension writes them, so none are written'

ReleaseNotes

Bases: Protocol

What a release-notes provider answers.

Methods:

Name Description
entry

The notes the commits since package's last release earn.

record

Write version's entry into package's history.

verify

The problems with version's recorded notes; empty when sound.

entry

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

The notes the commits since package's last release earn.

Headed by version when one is given, as unreleased otherwise; empty when nothing unreleased touches the package.

Source code in packages/workshop/src/livery/workshop/_release_notes.py
def entry(self, root: Path, package: Package, version: str = "") -> str:
    """The notes the commits since *package*'s last release earn.

    Headed by *version* when one is given, as unreleased otherwise;
    empty when nothing unreleased touches the package.
    """
    ...

record

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

Write version's entry into package's history.

An empty entry records a placeholder for a person to write. Returns the files changed, each with a note for the reader, empty when the history already holds the version's entry.

Source code in packages/workshop/src/livery/workshop/_release_notes.py
def record(self, package: Package, version: str, entry: str) -> list[str]:
    """Write *version*'s *entry* into *package*'s history.

    An empty *entry* records a placeholder for a person to write.
    Returns the files changed, each with a note for the reader,
    empty when the history already holds the version's entry.
    """
    ...

verify

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

The problems with version's recorded notes; empty when sound.

Source code in packages/workshop/src/livery/workshop/_release_notes.py
def verify(self, package: Package, version: str) -> list[str]:
    """The problems with *version*'s recorded notes; empty when sound."""
    ...

release_notes

release_notes(root: Path) -> ReleaseNotes | None

The provider the extensions listed at root answer; None when none answers.

The answer is imported when first asked, so a mount imports none of the answering extension's code.

Raises:

Type Description
QueryError

when two listed extensions answer and neither requires the other, naming both.

Source code in packages/workshop/src/livery/workshop/_release_notes.py
def release_notes(root: Path) -> ReleaseNotes | None:
    """The provider the extensions listed at *root* answer; None when none answers.

    The answer is imported when first asked, so a mount imports none
    of the answering extension's code.

    Raises:
        QueryError: when two listed extensions answer and neither
            requires the other, naming both.
    """
    return answer(root, RELEASE_NOTES)