#rlsbl.changelog.generate

#rlsbl.changelog.generate

Generate a Markdown CHANGELOG.md from structured JSONL changelog entries, grouping them by version with configurable formatting.

Per-version file permission model:

• x.y.z.jsonl -- the finalized, immutable changelog record. Locked to

0o444 at finalization; never rewritten in place.

• x.y.z.md -- a regenerated derivative of the JSONL. Normally writable,

but a user or tool may reasonably lock it (mirroring the 444 .jsonl it sits beside). generate_version_file therefore compares content first and, when it must rewrite the .md, writes atomically (tmp-in-same-dir + os.replace) with the replacement carrying the file's ORIGINAL mode (never assuming 444), so a deliberate lock survives regeneration and a crash mid-write can never leave a truncated file.

#_base_version

def _base_version(version: str) -> str

Strip the pre-release suffix from a version string.

"0.43.0-alpha.0" -> "0.43.0" "1.0.0" -> "1.0.0"

#_is_prerelease

def _is_prerelease(version: str) -> bool

Return True if the version has a pre-release suffix.

#_read_release_metadata

def _read_release_metadata(project_path: str, version: str, *, releases_dir: str | None=None) -> tuple[str, str]

Read description and context from an archived release toml file.

Looks for v{version}.toml in releases_dir (default: <project_path>/.rlsbl/releases/; releasable releases archive under the releasable's own releases dir) and extracts the description and context fields. Returns ("", "") if the file doesn't exist or can't be parsed.

#_read_release_metadata_full

def _read_release_metadata_full(project_path: str, version: str, *, releases_dir: str | None=None) -> tuple[str, str, str]

Read description, context, and bump type from an archived release toml file.

Looks for v{version}.toml in releases_dir (default: <project_path>/.rlsbl/releases/; releasable releases archive under the releasable's own releases dir) and extracts the description, context, and bump fields. Returns ("", "", "") if the file doesn't exist or can't be parsed.

#generate_version_section

def generate_version_section(version: str, entries: list[ChangelogEntry], *, description: str='', context: str='', bump_type: str | None=None) -> str

Generate markdown for one version section.

Only includes entries where user_facing=True. Groups by type under sub-headers (Breaking, Features, Fixes, Other). Empty groups are omitted. If no user-facing entries exist, emits a single "No user-facing changes." bullet.

If all entries share a release_type (e.g., "ota" or "build"), a marker is appended to the version heading.

When description is provided, it is added as a paragraph after the version heading and before the first type group. When context is provided, it is rendered as a collapsible <details> block after the description.

#_atomic_write_preserving_mode

def _atomic_write_preserving_mode(path: str, content: str) -> None

Atomically write content to path, preserving its EXACT mode.

Writes to a tmp file in the same directory and os.replaces it into place, so a crash mid-write can never leave a truncated file. os.replace is a directory operation, so it succeeds even when path itself is a read-only file -- there is no need to unlock the target first (unlike writable_jsonl, which relocks to 0o444). The replacement carries the target's ORIGINAL mode when the file exists (a per-version .md may be deliberately locked to any read-only mode; regeneration must not silently change it); a brand-new file uses the umask-derived default, matching the prior open(path, "w") behavior.

#generate_version_file

def generate_version_file(changes_dir: str, version: str, write_to_disk: bool=True, *, description: str='', context: str='', bump_type: str | None=None) -> str

Read the JSONL file for a version, generate markdown, optionally write .md alongside it.

Returns the generated markdown text. When write_to_disk is False, computes the markdown without touching the filesystem (used to preview content before pre-checks).

When description and context are provided, they are passed through to generate_version_section() so release metadata appears in the output.

#_deduplicate_entries

def _deduplicate_entries(entries: list[ChangelogEntry]) -> list[ChangelogEntry]

Remove duplicate entries based on commit hash sets.

Two entries are duplicates when they have the same set of commits. The first occurrence wins (preserves order).

#_generate_consolidated_section

def _generate_consolidated_section(stable_version: str, all_entries: list[ChangelogEntry], prerelease_versions: list[str], prerelease_entries_by_version: dict[str, list[ChangelogEntry]], *, description: str='', context: str='', bump_type: str | None=None) -> str

Generate a consolidated section for a stable version with pre-release predecessors.

Produces:

1. The stable heading (## 0.43.0) with ALL entries deduplicated
2. A note listing the pre-release cycle
3. Individual pre-release headings (### 0.43.0-alpha.0) with their entries

#_read_changelog_format

def _read_changelog_format(project_path: str) -> str

Read changelog_format from project config, defaulting to 'grouped'.

#generate_changelog

def generate_changelog(project_path: str, *, write_to_disk: bool=True, version_override: str | None=None, description: str='', context: str='', changes_dir_override: str | None=None, changelog_output_path: str | None=None, releases_dir_override: str | None=None, bump_type: str | None=None) -> str

Generate the complete CHANGELOG.md from .rlsbl/changes/ JSONL files.

1. Reads changelog_format from config (only "grouped" supported).
2. Reads unreleased.jsonl (if non-empty) for an Unreleased section.
3. Reads all versioned JSONL files sorted newest-first.
4. Generates per-version .md files alongside the JSONL files (when write_to_disk).
5. Writes CHANGELOG.md at project root (when write_to_disk).
6. Returns the generated content.

When write_to_disk is False, computes and returns the markdown content without modifying the filesystem. This lets callers preview the changelog before pre-release checks run, so an aborted release leaves a clean working tree.

When version_override is provided, the section heading is "## {version_override}" instead of "## Unreleased", and the section is emitted even when unreleased.jsonl is empty (that is what an infra release is). Versioned sections (from existing JSONL files) are unaffected. With version_override None and no unreleased entries, no section is emitted.

description and context are applied to the unreleased section only (the current release being prepared). Previously released version sections read their description and context from archived release files at .rlsbl/releases/v{version}.toml.

changes_dir_override overrides the default .rlsbl/changes/ path. Used in explicit releasable mode where the changes dir lives under the releasable directory.

changelog_output_path overrides the default CHANGELOG.md output location. Used in explicit releasable mode to write CHANGELOG.md into the releasable directory instead of the project root.

releases_dir_override overrides the default .rlsbl/releases/ path used for the archived-release-file metadata backfill (description, context, bump type of versioned sections). Used in explicit releasable mode where v{version}.toml archives live under the releasable directory.

bump_type is passed through to generate_version_section() for the unreleased section. For versioned sections, the bump type is read from the archived release file.