oct.git.changelog module

oct.git.changelog module#

Purpose#

Generate a Keep a Changelog formatted changelog from Conventional Commits history (Phase 4E — G-E1).

Responsibilities#

  • Parse git log output into structured changelog entries.

  • Map Conventional Commits types to Keep a Changelog sections.

  • Render changelog in Markdown and JSON formats.

Diagnostics#

Domain: GIT Levels:

L2 — changelog generation lifecycle L3 — entry collection details L4 — per-commit parsing trace

Contracts#

  • collect_changelog_entries returns an empty list on fresh repos.

  • format_changelog always returns valid Markdown.

  • Non-conventional commits are silently skipped (never raises).

class oct.git.changelog.ChangelogEntry(section: str, scope: str | None, subject: str, breaking: bool, sha: str)[source]#

Bases: object

One parsed commit mapped to a changelog section.

breaking: bool#
scope: str | None#
section: str#
sha: str#
subject: str#
oct.git.changelog.changelog_to_json(entries: list[ChangelogEntry], version: str | None = None) → dict[source]#

Return structured dict for --json output.

oct.git.changelog.collect_changelog_entries(repo_root: Path, since_ref: str | None = None) → list[ChangelogEntry][source]#

Read git log, parse each conventional commit, return entries.

Non-conventional commits are silently skipped. If since_ref is None, the latest tag is used; if no tags exist, the entire history is scanned.

oct.git.changelog.format_changelog(entries: list[ChangelogEntry], version: str | None = None) → str[source]#

Render entries in Keep a Changelog format.

Groups entries by section in the canonical order. If version is provided, the header uses ## [version] - YYYY-MM-DD; otherwise ## [Unreleased].