rlsbl v0.92.0 /rlsbl.changelog.files
Updated
On this page

File management for JSONL changelog files: reading, writing, appending entries, version finalization, stale-entry detection, and path resolution.

#rlsbl.changelog.files

#rlsbl.changelog.files

File management layer for JSONL changelog files including reading, writing, appending entries, and path resolution for .rlsbl directories.

#RemapResult

Result of remapping hashes in one JSONL file.

#_parse_semver

python
def _parse_semver(filename: str) -> _SemverKey | None

Extract a sort key from a versioned filename, or None.

Returns (major, minor, patch, is_stable, preid_rank, counter) where is_stable is 1 for stable versions (so they sort after pre-releases) and preid_rank maps alpha=0, beta=1, rc=2.

#get_changes_dir

python
def get_changes_dir(project_path: str) -> str

Return the path to .rlsbl/changes/ inside the project.

#changes_dir_exists

python
def changes_dir_exists(project_path: str) -> bool

Check if .rlsbl/changes/ exists in the project.

#list_versioned_files

python
def list_versioned_files(changes_dir: str) -> list[tuple[str, str]]

List all versioned JSONL files, sorted by semver (newest first).

Matches both stable (x.y.z.jsonl) and pre-release (x.y.z-preid.N.jsonl) filenames.

Returns (version_string, filepath) pairs.

#read_unreleased

python
def read_unreleased(changes_dir: str) -> list[ChangelogEntry]

Read unreleased.jsonl and return entries. Empty list if file missing.

#append_entry

python
def append_entry(changes_dir: str, entry: ChangelogEntry) -> None

Append one entry to unreleased.jsonl atomically.

Writes the serialized line to a temp file, then appends it to the target. Creates the changes directory and unreleased.jsonl if they don't exist.

#append_entry_to_version

python
def append_entry_to_version(changes_dir: str, version: str, entry: ChangelogEntry) -> None

Append one entry to a versioned JSONL file (e.g., 0.39.0.jsonl).

The caller is responsible for unlocking/re-locking the file if it is read-only.

#_append_entry_to_file

python
def _append_entry_to_file(target: str, entry: ChangelogEntry) -> None

Append one entry to any JSONL file atomically.

Writes the serialized line to a temp file, then appends it to the target. Creates parent directories if they don't exist.

#_warn_stale_entries

python
def _warn_stale_entries(src: str, tag_glob: str) -> None

Warn on stderr for entries in unreleased.jsonl referencing out-of-range commits.

In monorepo mode, an entry whose commits all sit before the project's last tag is stale — typically left over from a sibling project's release. We emit a warning per stale entry but do not strip them (warn-only).

#finalize_version

python
def finalize_version(changes_dir: str, version: str, tag_glob: str | None=None) -> None

Rename unreleased.jsonl to x.y.z.jsonl and create a fresh unreleased.jsonl.

Sets the versioned file read-only (chmod 0o444). Raises FileNotFoundError if unreleased.jsonl doesn't exist.

When tag_glob is provided (monorepo mode), inspects each entry in unreleased.jsonl before the rename and warns on stderr for any whose commits fall outside the current project's unreleased range. Warn-only: the stale entries are not stripped.

#unfinalize_version

python
def unfinalize_version(changes_dir: str, version: str) -> list[str]

Reverse a finalize_version: restore x.y.z.jsonl back to unreleased.jsonl.

  1. Makes the versioned file writable.
  2. Renames it to unreleased.jsonl.
  3. Deletes the per-version .md file if present.
  4. Returns the list of changed file paths (for committing).

Returns an empty list if the versioned file doesn't exist.

#is_read_only

python
def is_read_only(path: str) -> bool

Check if a file has no write permissions (for any user class).

#writable_jsonl

python
def writable_jsonl(path)

Context manager that temporarily makes a read-only JSONL file writable.

If the file is already writable, yields without changing permissions. On exit (even after exceptions), restores original read-only state.

#remap_jsonl_hashes

python
def remap_jsonl_hashes(changes_dir, sha_map)

Replace commit hashes in all JSONL files using a mapping.

Scans unreleased.jsonl and all versioned *.jsonl files in changes_dir. Only modifies files that contain hashes present in sha_map. Uses writable_jsonl to handle read-only versioned files.

Returns a list of RemapResult for each file that was modified. Returns an empty list if changes_dir does not exist or no files match.