Changelog

The changelog as data, as the server serves it at /changelog.

changelog

The engine's own changelog, as data.

The app (Beacon) shows the user what the engine they are running has changed. It learns the engine's version from /health, so the changelog comes from the engine for the same reason: the notes have to be for the engine actually running, not whatever the app was built against.

An installed wheel carries a copy of CHANGELOG.md inside the package, because an installed engine has no repository beside it. An editable install reads the file at the repository root directly.

The format is Keep a Changelog: ## [version] - date, then ### Added, ### Changed and so on, each a list of - items. Items stay markdown, so the emphasis and code spans in them survive to whatever renders them.

ChangelogSection dataclass

ChangelogSection(heading: str, items: list[str] = list())

One heading under a release, e.g. "Added", and its items.

ChangelogEntry dataclass

ChangelogEntry(
    version: str,
    date: str | None,
    sections: list[ChangelogSection] = list(),
)

One release: its version, its date, and what changed in it.

date is None for the Unreleased entry, which has none.

parse

parse(text: str) -> list[ChangelogEntry]

Read a Keep a Changelog document into entries, newest first.

Prose between a release heading and its first section (a note that nothing has been released yet, say) is not an item and is skipped. A list item that wraps onto indented lines is joined back into one string.

newer_than

newer_than(
    entries: list[ChangelogEntry], since: str
) -> list[ChangelogEntry]

The entries released after since, for "what's new" in a client.

Compared as numbers, so 0.10.0 is after 0.9.0, and a since this changelog does not list still works: an app that last saw a newer engine gets nothing, not the whole history. Unreleased has no number and is always included.

Raises:

Type	Description
ValueError	If since is not a dotted version such as 0.1.0.

read

read() -> str

The changelog text for this installation.

Raises:

Type	Description
FileNotFoundError	If neither the packaged copy nor the repository file exists, which means the wheel was built wrongly.

entries

entries() -> list[ChangelogEntry]

This installation's changelog, newest first.