diff --git a/.zed/rules b/.zed/rules index 0c226b8ac..57b230f3e 100644 --- a/.zed/rules +++ b/.zed/rules @@ -183,6 +183,25 @@ Examples: - test(function_pod): add schema validation tests - refactor(schema_utils): use Schema.optional_fields directly +## Changelog + +A pull request never edits CHANGELOG.md (developer, November 11, 2026; ITL-961). It adds +exactly one file, changelog.d/.md (e.g. changelog.d/ITL-955.md; a PR that +resolves several issues uses its primary issue's id). + +- The file holds only the text that would have gone under the release heading in + CHANGELOG.md: the same category headings CHANGELOG.md uses + (### Breaking changes and migration, ### Added, ### Changed, ### Fixed, + ### Known limitations), each followed by its bullet lines; no version heading, no date. +- If your branch already edits CHANGELOG.md, restore CHANGELOG.md to its state on the + branch's base and move that text, unchanged, into the fragment. +- Check a fragment with uv run python scripts/assemble_changelog.py --check + (tests/test_changelog_fragments.py runs it in CI). +- Only the release PR changes CHANGELOG.md: it folds the fragments in with + uv run python scripts/assemble_changelog.py --version X.Y.Z, which also deletes them + (see RELEASING.md). Entries already in CHANGELOG.md on main stay there. +- changelog.d/README.md is the full statement of the convention. + ## Lint, format and type checks Every pull request must pass the metamorphic-labs required CI, which runs exactly these diff --git a/CLAUDE.md b/CLAUDE.md index 1908ec144..031e2e443 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -192,6 +192,25 @@ Examples: - `test(function_pod): add schema validation tests` - `refactor(schema_utils): use Schema.optional_fields directly` +## Changelog + +A pull request never edits `CHANGELOG.md` (developer, November 11, 2026; ITL-961). It adds +exactly one file, `changelog.d/.md` (e.g. `changelog.d/ITL-955.md`; a PR that +resolves several issues uses its primary issue's id). + +- The file holds only the text that would have gone under the release heading in + `CHANGELOG.md`: the same category headings `CHANGELOG.md` uses + (`### Breaking changes and migration`, `### Added`, `### Changed`, `### Fixed`, + `### Known limitations`), each followed by its bullet lines; no version heading, no date. +- If your branch already edits `CHANGELOG.md`, restore `CHANGELOG.md` to its state on the + branch's base and move that text, unchanged, into the fragment. +- Check a fragment with `uv run python scripts/assemble_changelog.py --check` + (`tests/test_changelog_fragments.py` runs it in CI). +- Only the release PR changes `CHANGELOG.md`: it folds the fragments in with + `uv run python scripts/assemble_changelog.py --version X.Y.Z`, which also deletes them + (see `RELEASING.md`). Entries already in `CHANGELOG.md` on `main` stay there. +- `changelog.d/README.md` is the full statement of the convention. + ## Lint, format and type checks Every pull request must pass the metamorphic-labs required CI, which runs exactly these diff --git a/RELEASING.md b/RELEASING.md index 6cdda6c41..d565f497f 100644 --- a/RELEASING.md +++ b/RELEASING.md @@ -28,9 +28,26 @@ requires, on each index, a trusted publisher for the `orcapod` project naming ow Do these on `main` before triggering the workflow: -1. **Update `CHANGELOG.md`** — rename the top section to the version being released, set - its date, and make sure breaking changes carry migration notes. The GitHub Release - body is generated from PR titles; `CHANGELOG.md` is the curated record. +1. **Update `CHANGELOG.md`** in a release pull request, the only kind of pull request that + edits it. Feature pull requests add `changelog.d/.md` fragments instead (see + `changelog.d/README.md`). + 1. Fold the fragments into the section of the version being released: + + ``` + uv run python scripts/assemble_changelog.py --version X.Y.Z + ``` + + This appends each fragment's text to the matching category of `## [X.Y.Z]` (in order + of issue id, without moving the lines already there), creates the section or a + category if it is missing, and deletes the fragments. It stops without changing + anything if a fragment is malformed; `--check` reports the same problems without + folding. Commit the changed `CHANGELOG.md` and the deleted fragments together; + `changelog.d/README.md` stays. + 2. Set the section's heading to the version being released and its date + (`## [X.Y.Z] — YYYY-MM-DD`), and make sure breaking changes carry migration notes. + + The GitHub Release body is generated from PR titles; `CHANGELOG.md` is the curated + record. 2. **Check that `main` is green** — the `Run Tests` workflow on the commit you are releasing. The Release workflow re-runs the unit tests on Python 3.11, 3.12 and 3.13 and the license check, but not the PostgreSQL or SpiralDB integration jobs. diff --git a/changelog.d/README.md b/changelog.d/README.md new file mode 100644 index 000000000..eb4154b7d --- /dev/null +++ b/changelog.d/README.md @@ -0,0 +1,69 @@ +# Changelog fragments + +A pull request never edits `CHANGELOG.md` (developer, November 11, 2026; ITL-961). It adds +exactly one file here instead, so two open pull requests never conflict on the changelog. + +## The rule + +- The file is `changelog.d/.md`, for example `changelog.d/ITL-955.md`. A pull + request that resolves several issues uses its primary issue's id. +- The file holds only the text that would have gone under the release heading in + `CHANGELOG.md`: the same category headings `CHANGELOG.md` uses, each followed by its + bullet lines. No version heading, no date. +- If your branch already edits `CHANGELOG.md`, restore `CHANGELOG.md` to its state on the + branch's base and move that text, unchanged, into the fragment. +- A change with nothing to tell users (tests, internal tooling) adds no fragment. + +The category headings, in the order they appear in a release section: + +```markdown +### Breaking changes and migration +### Added +### Changed +### Fixed +### Known limitations +``` + +Use only the ones you need. Under a heading, write what `CHANGELOG.md` has today: bullet +lines, or a `####` sub-heading followed by paragraphs for a change that needs explaining. + +## Example + +`changelog.d/ITL-955.md`: + +```markdown +### Added + +- **`orcapod.errors.StoreError`** — the base of `StoreReadError` and `StoreWriteError`. + (ITL-955 #301) + +### Fixed + +- `Join` no longer raises on an empty right-hand stream. (ITL-955 #301) +``` + +## Checking a fragment + +``` +uv run python scripts/assemble_changelog.py --check +``` + +fails if a file in this directory other than `README.md` is not named `.md`, is +empty, has text before its first category heading, has a heading that is not one of the +categories above (`####` and deeper are fine), repeats a category, leaves a category empty, +or has a code fence that is never closed. `tests/test_changelog_fragments.py` runs the same +check, so CI rejects a malformed fragment. + +## At release + +The release pull request folds the fragments into `CHANGELOG.md` and deletes them (see +`RELEASING.md`): + +``` +uv run python scripts/assemble_changelog.py --version 0.3.0 +``` + +Each category's text is appended to the same category of the `## [0.3.0]` section, in order +of issue id (team key, then issue number). Lines already in `CHANGELOG.md` are not moved or +changed: entries that were in `CHANGELOG.md` on `main` before this convention stay there. +This file stays; only the fragments are deleted. diff --git a/scripts/assemble_changelog.py b/scripts/assemble_changelog.py new file mode 100644 index 000000000..5baec9a02 --- /dev/null +++ b/scripts/assemble_changelog.py @@ -0,0 +1,381 @@ +"""Fold the changelog fragments in ``changelog.d/`` into ``CHANGELOG.md``. + +A pull request never edits ``CHANGELOG.md``. It adds one fragment, +``changelog.d/.md``, holding the category headings and text that belong under +the release heading (see ``changelog.d/README.md``). The release pull request runs this +script to move every fragment into the release section and delete it. + +Usage: + + uv run python scripts/assemble_changelog.py --check + uv run python scripts/assemble_changelog.py --version 0.3.0 + +``--check`` only validates the fragments and changes nothing. Without it, the fragments +are folded into the ``## []`` section of ``CHANGELOG.md`` and deleted. The +script uses the standard library only. +""" + +from __future__ import annotations + +import argparse +import re +import sys +from collections.abc import Sequence +from pathlib import Path + +REPO_ROOT = Path(__file__).resolve().parents[1] + +# The category headings CHANGELOG.md uses, in the order they appear in a release section. +CATEGORIES = ( + "### Breaking changes and migration", + "### Added", + "### Changed", + "### Fixed", + "### Known limitations", +) + +README_NAME = "README.md" +_FRAGMENT_NAME = re.compile(r"^([A-Z][A-Z0-9]*)-([0-9]+)\.md$") +_HEADING = re.compile(r"^(#{1,6})\s") +_FENCE = re.compile(r"^ {0,3}(`{3,}|~{3,})(.*)$") +_BULLET = re.compile(r"^[-*+] ") + + +class FragmentError(ValueError): + """A fragment's text does not follow the convention. + + Attributes: + problems: One sentence fragment per problem found, without the file name. + """ + + def __init__(self, problems: Sequence[str]) -> None: + super().__init__("; ".join(problems)) + self.problems = tuple(problems) + + +def _scan_fences(lines: Sequence[str]) -> tuple[list[bool], bool]: + """Find the fenced code blocks in Markdown lines. + + A block is closed only by a fence of the same character that is at least as long + as the one that opened it, so a three-backtick line inside a four-backtick block + is part of the block. + + Args: + lines: The lines of a Markdown text. + + Returns: + A mask that is true for each line outside every fenced code block (fence + lines themselves are inside), and whether the last block is never closed. + """ + mask: list[bool] = [] + opener: str | None = None + for line in lines: + fence = _FENCE.match(line) + if opener is None: + # A backtick fence cannot have a backtick in its info string. + if fence and not (fence.group(1)[0] == "`" and "`" in fence.group(2)): + opener = fence.group(1) + mask.append(False) + else: + mask.append(True) + continue + mask.append(False) + if ( + fence + and fence.group(1)[0] == opener[0] + and len(fence.group(1)) >= len(opener) + and not fence.group(2).strip() + ): + opener = None + return mask, opener is not None + + +def _outside_fences(lines: Sequence[str]) -> list[bool]: + """Mark the lines that are not inside (or delimiting) a fenced code block.""" + return _scan_fences(lines)[0] + + +def _strip_blank_edges(lines: Sequence[str]) -> list[str]: + start, end = 0, len(lines) + while start < end and not lines[start].strip(): + start += 1 + while end > start and not lines[end - 1].strip(): + end -= 1 + return list(lines[start:end]) + + +def parse_fragment(text: str) -> dict[str, list[str]]: + """Split a fragment into its categories. + + Args: + text: The fragment's full text. + + Returns: + A mapping from category heading (``### Added``) to that category's lines, + without surrounding blank lines and without line endings. + + Raises: + FragmentError: If the fragment is empty, has text before its first category + heading, has a level 1 or 2 heading, has an unknown or repeated category + heading, has a category with no text, or has a code fence that is never + closed. + """ + if not text.strip(): + raise FragmentError(["is empty"]) + + lines = text.splitlines() + problems: list[str] = [] + categories: dict[str, list[str]] = {} + current: list[str] | None = None + mask, unclosed_fence = _scan_fences(lines) + if unclosed_fence: + problems.append("has a code fence that is never closed") + for line, is_markdown in zip(lines, mask, strict=True): + heading = _HEADING.match(line) if is_markdown else None + level = len(heading.group(1)) if heading else 0 + if level in (1, 2): + problems.append( + f"has the heading {line.rstrip()!r}; a fragment holds only category " + "headings, no title, version or date" + ) + elif level == 3: + name = line.rstrip() + current = [] + if name not in CATEGORIES: + allowed = ", ".join(repr(c) for c in CATEGORIES) + problems.append( + f"has the unknown category heading {name!r} (allowed: {allowed})" + ) + elif name in categories: + problems.append(f"repeats the category heading {name!r}") + else: + categories[name] = current + elif current is not None: + current.append(line) + elif line.strip(): + problems.append(f"has text before the first category heading: {line!r}") + + for name, body in categories.items(): + categories[name] = _strip_blank_edges(body) + if not categories[name]: + problems.append(f"has no text under {name!r}") + if problems: + raise FragmentError(problems) + return categories + + +def _fragment_order(path: Path) -> tuple[str, int]: + match = _FRAGMENT_NAME.match(path.name) + assert match is not None # callers pass only validated fragment paths + return match.group(1), int(match.group(2)) + + +def load_fragments( + fragments_dir: Path, +) -> tuple[list[tuple[Path, dict[str, list[str]]]], list[str]]: + """Read and validate every fragment in a directory. + + ``README.md`` and dotfiles are skipped. Every other entry must be a fragment. + + Args: + fragments_dir: The ``changelog.d`` directory. + + Returns: + The valid fragments as ``(path, categories)`` ordered by team key and issue + number, and one message per problem found. + """ + fragments: list[tuple[Path, dict[str, list[str]]]] = [] + problems: list[str] = [] + for path in sorted(fragments_dir.iterdir()): + if path.name == README_NAME or path.name.startswith("."): + continue + if not path.is_file() or not _FRAGMENT_NAME.match(path.name): + problems.append( + f"{path}: not a fragment name; expected .md, " + "for example ITL-955.md" + ) + continue + try: + fragments.append((path, parse_fragment(path.read_text(encoding="utf-8")))) + except FragmentError as error: + problems.extend(f"{path}: {problem}" for problem in error.problems) + fragments.sort(key=lambda item: _fragment_order(item[0])) + return fragments, problems + + +def _ends_in_bullet(lines: Sequence[str]) -> bool: + """Whether the last block of ``lines`` is a top-level list item.""" + for line in reversed(lines): + if not line.strip(): + return False + if _BULLET.match(line): + return True + return False + + +def _append_block(existing: list[str], block: Sequence[str]) -> list[str]: + """Append ``block`` to ``existing`` text: one list if both are bullets.""" + if not existing: + return list(block) + joined_list = _ends_in_bullet(existing) and bool(_BULLET.match(block[0])) + return [*existing, *([] if joined_list else [""]), *block] + + +def _section_bounds(lines: Sequence[str], version: str) -> tuple[int, int] | None: + """Find ``## []``: the heading's index and the section's end index.""" + mask = _outside_fences(lines) + prefix = f"## [{version}]" + start = next( + (i for i, line in enumerate(lines) if mask[i] and line.startswith(prefix)), + None, + ) + if start is None: + return None + end = next( + ( + i + for i in range(start + 1, len(lines)) + if mask[i] and lines[i].startswith("## ") + ), + len(lines), + ) + return start, end + + +def _insert_section(lines: list[str], version: str) -> list[str]: + """Add an empty ``## [] — unreleased`` section above the newest one.""" + mask = _outside_fences(lines) + index = next( + (i for i, line in enumerate(lines) if mask[i] and line.startswith("## [")), + len(lines), + ) + before = lines[:index] + if before and before[-1].strip(): + before.append("") + return [*before, f"## [{version}] — unreleased", "", *lines[index:]] + + +def _fold_category( + lines: list[str], version: str, category: str, block: Sequence[str] +) -> list[str]: + """Append ``block`` to ``category`` of the release section, adding it if absent.""" + bounds = _section_bounds(lines, version) + assert bounds is not None # the caller creates the section first + start, end = bounds + mask = _outside_fences(lines) + headings = [ + i for i in range(start + 1, end) if mask[i] and lines[i].startswith("### ") + ] + + existing = next((i for i in headings if lines[i].rstrip() == category), None) + if existing is not None: + body_end = next((i for i in headings if i > existing), end) + last = body_end + while last > existing + 1 and not lines[last - 1].strip(): + last -= 1 + body = lines[existing + 1 : last] + if _strip_blank_edges(body): + new_body = _append_block(body, block) + else: + new_body = ["", *block] + return [*lines[: existing + 1], *new_body, *lines[last:]] + + rank = CATEGORIES.index(category) + later = {c for c in CATEGORIES[rank + 1 :]} + at = next((i for i in headings if lines[i].rstrip() in later), end) + before = lines[:at] + if before and before[-1].strip(): + before.append("") + after = lines[at:] + return [*before, category, "", *block, *([""] if after else []), *after] + + +def fold( + changelog: str, version: str, fragments: Sequence[dict[str, list[str]]] +) -> str: + """Fold parsed fragments into one release section of a changelog. + + Each category's text is appended, fragment by fragment in the order given, at the + end of that category in the ``## []`` section. Existing lines keep their + order and content. A category the section lacks is inserted in the order of + ``CATEGORIES``; a missing section is created above the newest one. + + Args: + changelog: The full text of ``CHANGELOG.md``. + version: The release whose section receives the text, for example ``0.3.0``. + fragments: The parsed fragments, as returned by ``parse_fragment``. + + Returns: + The new full text of the changelog. + """ + lines = changelog.splitlines() + if _section_bounds(lines, version) is None: + lines = _insert_section(lines, version) + for category in CATEGORIES: + block: list[str] = [] + for fragment in fragments: + if category in fragment: + block = _append_block(block, fragment[category]) + if block: + lines = _fold_category(lines, version, category, block) + return "\n".join(lines) + "\n" + + +def main(argv: Sequence[str] | None = None) -> int: + """Validate the fragments, and unless ``--check`` is given, fold and delete them. + + Args: + argv: Command-line arguments; ``sys.argv[1:]`` when omitted. + + Returns: + The process exit code: 0 on success, 1 if any fragment is malformed. + """ + parser = argparse.ArgumentParser(description=(__doc__ or "").split("\n\n")[0]) + parser.add_argument( + "--version", + help="release section to fold into, e.g. 0.3.0 (required unless --check)", + ) + parser.add_argument( + "--check", + action="store_true", + help="only validate the fragments; change nothing", + ) + parser.add_argument( + "--changelog", type=Path, default=REPO_ROOT / "CHANGELOG.md", help="changelog" + ) + parser.add_argument( + "--fragments-dir", + type=Path, + default=REPO_ROOT / "changelog.d", + help="directory holding the fragments", + ) + args = parser.parse_args(argv) + if not args.check and not args.version: + parser.error("--version is required unless --check is given") + + fragments, problems = load_fragments(args.fragments_dir) + if problems: + print("\n".join(problems), file=sys.stderr) + return 1 + if args.check: + print(f"{len(fragments)} changelog fragment(s) OK") + return 0 + if not fragments: + print("No changelog fragments to fold.") + return 0 + + version = args.version.removeprefix("v") + text = args.changelog.read_text(encoding="utf-8") + new_text = fold(text, version, [categories for _, categories in fragments]) + args.changelog.write_text(new_text, encoding="utf-8") + for path, _ in fragments: + path.unlink() + print( + f"Folded {len(fragments)} fragment(s) into [{version}] of {args.changelog} " + "and deleted them." + ) + return 0 + + +if __name__ == "__main__": + raise SystemExit(main()) diff --git a/superpowers/plans/2026-11-11-itl-961-changelog-fragments.md b/superpowers/plans/2026-11-11-itl-961-changelog-fragments.md new file mode 100644 index 000000000..e555746ba --- /dev/null +++ b/superpowers/plans/2026-11-11-itl-961-changelog-fragments.md @@ -0,0 +1,77 @@ +# Changelog Fragments Implementation Plan (ITL-961) + +> **For agentic workers:** REQUIRED SUB-SKILL: Use sensei:executing-plans to implement this plan +> task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking. + +**Goal:** A pull request adds `changelog.d/.md` instead of editing `CHANGELOG.md`; the +release PR folds the fragments into `CHANGELOG.md` with a standard-library script. + +**Architecture:** One script, `scripts/assemble_changelog.py`, owns the fragment rules (file +name, category headings, non-empty) and the fold. Tests drive it as a command +(`python scripts/assemble_changelog.py ...`), and one test runs `--check` on the repository's +own `changelog.d/` so CI rejects a malformed fragment. + +**Tech stack:** Python standard library only (`argparse`, `pathlib`, `re`). No new dependency. + +--- + +## Decisions + +- **Category headings** (exactly those `CHANGELOG.md` uses in `[0.3.0]` and `[0.2.0]`), in + this canonical order: `### Breaking changes and migration`, `### Added`, `### Changed`, + `### Fixed`, `### Known limitations`. The older `### New` / `### Breaking Changes` of + `0.1.1` are not accepted. +- **Fragment name:** `-.md` (`ITL-955.md`, `PLT-12.md`). `README.md` is the only + other file allowed in `changelog.d/`. +- **Fragment body:** only `### ` headings, each followed by non-empty text (bullets, + `####` sub-headings, paragraphs, as `CHANGELOG.md` has today). Text before the first heading, + an unknown or repeated heading, an empty category, a `#`/`##` heading, or an empty file is an + error. `#` lines inside fenced code blocks are not headings. +- **Fold:** fragments in order of (team key, issue number). For each category, the fragment + text is appended at the end of that category in the release section; existing lines are + never reordered or changed. A category missing from the section is inserted in canonical + order (before the first existing later category, else at the end of the section). A missing + release section is created above the first `## [` section as `## [X.Y.Z] — unreleased`. + When the existing category ends in a bullet and the appended text starts with one, they are + joined without a blank line (one list); otherwise one blank line separates them. +- **Release heading / date** stay a manual step in `RELEASING.md` (unchanged scope). +- **CLI:** `uv run python scripts/assemble_changelog.py --version 0.3.0` folds and deletes; + `--check` validates only (no `--version` needed). `--changelog` and `--fragments-dir` + default to the repository's paths. Exit 0 on success, 1 with one line per problem on stderr. +- **This PR's fragment:** none. The change is contributor process, not a user-visible change + of the library, so it has no changelog text. +- **Docs/tests reading `CHANGELOG.md`:** none (`mkdocs.yml` and the doc-sample tests do not + reference it; the sdist is `only-include`, so `changelog.d/` and `scripts/` are not shipped). + +## Tasks + +### Task 1: failing tests + +- [ ] Create `tests/test_changelog_fragments.py` running the script with `subprocess`: + check mode (valid, wrong name, unknown heading, empty, text before heading, empty category, + heading inside a code fence), fold (appends to the right categories without reordering, + order by issue number, inserts a missing category in canonical order, creates a missing + section, deletes fragments, keeps `README.md`, leaves other sections byte-identical, refuses + to fold and changes nothing when a fragment is malformed), and + `test_repository_fragments_are_well_formed` on the real `changelog.d/`. +- [ ] `uv run pytest tests/test_changelog_fragments.py` fails (script missing). + +### Task 2: script + +- [ ] Create `scripts/assemble_changelog.py`; tests pass; ruff and basedpyright clean. + +### Task 3: convention and docs + +- [ ] `changelog.d/README.md`. +- [ ] "Changelog" section in `CLAUDE.md` and `.zed/rules`. +- [ ] `RELEASING.md` "Before You Cut" step 1: run the script, then set the heading and date. +- [ ] Commit, push. + +### Task 4: finish + +- [ ] Full `uv run pytest tests/`, ruff check, ruff format --check, basedpyright. +- [ ] PR against `main` (`Fixes ITL-961`), CodeRabbit rounds, CI green, `worker_done`. + +## Notes for a successor + +- PR #320 open. CodeRabbit round 1 (2 findings: fence matching, unclosed fence) accepted by coordinator and fixed. diff --git a/tests/test_changelog_fragments.py b/tests/test_changelog_fragments.py new file mode 100644 index 000000000..4a03c5755 --- /dev/null +++ b/tests/test_changelog_fragments.py @@ -0,0 +1,440 @@ +"""Changelog fragments (``changelog.d/``) and the release fold (ITL-961). + +Every test drives ``scripts/assemble_changelog.py`` as a command, the way a release PR +and CI use it. +""" + +from __future__ import annotations + +import subprocess +import sys +from pathlib import Path + +import pytest + +REPO_ROOT = Path(__file__).resolve().parents[1] +SCRIPT = REPO_ROOT / "scripts" / "assemble_changelog.py" + +CHANGELOG = """\ +# Changelog + +## [0.3.0] — unreleased + +### Breaking changes and migration + +#### Arrays changed (ITL-1) + +Existing paragraph. + +### Added + +- Existing added one. (ITL-2) +- Existing added two, + wrapped. (ITL-3) + +### Fixed + +#### A fix with a sub-heading (ITL-4) + +Existing fixed paragraph. + +## [0.2.0] — 2026-11-10 + +Intro text. + +### Added + +- Old added. (ITL-0) + +### Changed + +- Old changed. +""" + + +def _run(*args: str | Path) -> subprocess.CompletedProcess[str]: + return subprocess.run( + [sys.executable, str(SCRIPT), *map(str, args)], + capture_output=True, + text=True, + check=False, + ) + + +@pytest.fixture +def workspace(tmp_path: Path) -> tuple[Path, Path]: + """A changelog file and a fragments directory holding only its README.""" + changelog = tmp_path / "CHANGELOG.md" + changelog.write_text(CHANGELOG, encoding="utf-8") + fragments = tmp_path / "changelog.d" + fragments.mkdir() + (fragments / "README.md").write_text("# Fragments\n", encoding="utf-8") + return changelog, fragments + + +def _check(fragments: Path) -> subprocess.CompletedProcess[str]: + return _run("--check", "--fragments-dir", fragments) + + +def _fold( + changelog: Path, fragments: Path, version: str = "0.3.0" +) -> subprocess.CompletedProcess[str]: + return _run( + "--version", version, "--changelog", changelog, "--fragments-dir", fragments + ) + + +# --- the repository's own fragments ------------------------------------------------- + + +def test_repository_fragments_are_well_formed() -> None: + """Every file in ``changelog.d/`` except ``README.md`` is a valid fragment.""" + result = _run("--check") + assert result.returncode == 0, result.stderr + + +def test_repository_fragments_directory_has_a_readme() -> None: + assert (REPO_ROOT / "changelog.d" / "README.md").is_file() + + +# --- --check ------------------------------------------------------------------------ + + +def test_check_accepts_a_directory_with_only_the_readme( + workspace: tuple[Path, Path], +) -> None: + result = _check(workspace[1]) + assert result.returncode == 0, result.stderr + + +def test_check_accepts_a_valid_fragment(workspace: tuple[Path, Path]) -> None: + _, fragments = workspace + (fragments / "ITL-955.md").write_text( + "### Added\n\n- New thing. (ITL-955)\n\n" + "### Fixed\n\n#### A sub-heading\n\nParagraph.\n", + encoding="utf-8", + ) + result = _check(fragments) + assert result.returncode == 0, result.stderr + + +@pytest.mark.parametrize( + "name", + [ + "itl-955.md", + "ITL-955.txt", + "955.md", + "ITL-955-extra.md", + "notes.md", + "ITL_955.md", + ], +) +def test_check_rejects_a_wrong_file_name( + workspace: tuple[Path, Path], name: str +) -> None: + _, fragments = workspace + (fragments / name).write_text("### Added\n\n- Thing.\n", encoding="utf-8") + result = _check(fragments) + assert result.returncode == 1 + assert name in result.stderr + + +@pytest.mark.parametrize( + ("body", "expected"), + [ + ("### Add\n\n- Thing.\n", "### Add"), + ("### Breaking changes\n\n- Thing.\n", "### Breaking changes"), + ("### added\n\n- Thing.\n", "### added"), + ("## [0.3.0] — unreleased\n\n### Added\n\n- Thing.\n", "## [0.3.0]"), + ("- Thing with no heading.\n", "before the first"), + ("### Added\n\n### Fixed\n\n- Thing.\n", "### Added"), + ("### Added\n\n- One.\n\n### Added\n\n- Two.\n", "### Added"), + ("", "empty"), + ("\n\n \n", "empty"), + ], +) +def test_check_rejects_a_malformed_fragment( + workspace: tuple[Path, Path], body: str, expected: str +) -> None: + _, fragments = workspace + (fragments / "ITL-7.md").write_text(body, encoding="utf-8") + result = _check(fragments) + assert result.returncode == 1 + assert "ITL-7.md" in result.stderr + assert expected in result.stderr + + +def test_check_ignores_heading_like_lines_inside_a_code_fence( + workspace: tuple[Path, Path], +) -> None: + _, fragments = workspace + (fragments / "ITL-7.md").write_text( + "### Added\n\n- Thing:\n\n```python\n### not a heading\n## nor this\n```\n", + encoding="utf-8", + ) + result = _check(fragments) + assert result.returncode == 0, result.stderr + + +def test_check_keeps_a_shorter_fence_inside_a_longer_one( + workspace: tuple[Path, Path], +) -> None: + """A three-backtick line does not close a four-backtick block.""" + _, fragments = workspace + (fragments / "ITL-7.md").write_text( + "### Added\n\n- Thing:\n\n````markdown\n```\n### Nope\n```\n````\n", + encoding="utf-8", + ) + result = _check(fragments) + assert result.returncode == 0, result.stderr + + +@pytest.mark.parametrize("fence", ["```", "~~~", "````text"]) +def test_check_rejects_an_unclosed_code_fence( + workspace: tuple[Path, Path], fence: str +) -> None: + _, fragments = workspace + (fragments / "ITL-7.md").write_text( + f"### Added\n\n- Thing:\n\n{fence}\nx = 1\n", encoding="utf-8" + ) + result = _check(fragments) + assert result.returncode == 1 + assert "ITL-7.md" in result.stderr + assert "never closed" in result.stderr + + +def test_fold_refuses_a_fragment_with_an_unclosed_code_fence( + workspace: tuple[Path, Path], +) -> None: + changelog, fragments = workspace + (fragments / "ITL-7.md").write_text( + "### Added\n\n- Thing:\n\n```\nx = 1\n", encoding="utf-8" + ) + result = _fold(changelog, fragments) + assert result.returncode == 1 + assert "never closed" in result.stderr + assert changelog.read_text(encoding="utf-8") == CHANGELOG + assert (fragments / "ITL-7.md").exists() + + +def test_check_reports_every_problem(workspace: tuple[Path, Path]) -> None: + _, fragments = workspace + (fragments / "ITL-7.md").write_text("", encoding="utf-8") + (fragments / "wrong.md").write_text("### Added\n\n- Thing.\n", encoding="utf-8") + result = _check(fragments) + assert result.returncode == 1 + assert "ITL-7.md" in result.stderr + assert "wrong.md" in result.stderr + + +def test_check_changes_nothing(workspace: tuple[Path, Path]) -> None: + changelog, fragments = workspace + (fragments / "ITL-7.md").write_text("### Added\n\n- Thing.\n", encoding="utf-8") + result = _run("--check", "--changelog", changelog, "--fragments-dir", fragments) + assert result.returncode == 0, result.stderr + assert changelog.read_text(encoding="utf-8") == CHANGELOG + assert (fragments / "ITL-7.md").exists() + + +# --- fold --------------------------------------------------------------------------- + + +def test_fold_appends_to_existing_categories_in_issue_order( + workspace: tuple[Path, Path], +) -> None: + changelog, fragments = workspace + (fragments / "ITL-100.md").write_text( + "### Added\n\n- Added by 100. (ITL-100)\n\n" + "### Fixed\n\n- Fixed by 100. (ITL-100)\n", + encoding="utf-8", + ) + # 20 sorts before 100 numerically, although "ITL-100" < "ITL-20" as text. + (fragments / "ITL-20.md").write_text( + "### Added\n\n- Added by 20,\n wrapped. (ITL-20)\n\n" + "### Breaking changes and migration\n\n#### Break by 20 (ITL-20)\n\nWhy.\n", + encoding="utf-8", + ) + + result = _fold(changelog, fragments) + + assert result.returncode == 0, result.stderr + assert ( + changelog.read_text(encoding="utf-8") + == """\ +# Changelog + +## [0.3.0] — unreleased + +### Breaking changes and migration + +#### Arrays changed (ITL-1) + +Existing paragraph. + +#### Break by 20 (ITL-20) + +Why. + +### Added + +- Existing added one. (ITL-2) +- Existing added two, + wrapped. (ITL-3) +- Added by 20, + wrapped. (ITL-20) +- Added by 100. (ITL-100) + +### Fixed + +#### A fix with a sub-heading (ITL-4) + +Existing fixed paragraph. + +- Fixed by 100. (ITL-100) + +## [0.2.0] — 2026-11-10 + +Intro text. + +### Added + +- Old added. (ITL-0) + +### Changed + +- Old changed. +""" + ) + + +def test_fold_deletes_the_fragments_and_keeps_the_readme( + workspace: tuple[Path, Path], +) -> None: + changelog, fragments = workspace + (fragments / "ITL-7.md").write_text("### Added\n\n- Thing.\n", encoding="utf-8") + (fragments / "PLT-8.md").write_text("### Fixed\n\n- Other.\n", encoding="utf-8") + + result = _fold(changelog, fragments) + + assert result.returncode == 0, result.stderr + assert sorted(p.name for p in fragments.iterdir()) == ["README.md"] + + +def test_fold_inserts_a_missing_category_in_canonical_order( + workspace: tuple[Path, Path], +) -> None: + changelog, fragments = workspace + (fragments / "ITL-7.md").write_text( + "### Known limitations\n\n- A limit. (ITL-7)\n\n" + "### Changed\n\n- A change. (ITL-7)\n", + encoding="utf-8", + ) + + result = _fold(changelog, fragments) + + assert result.returncode == 0, result.stderr + text = changelog.read_text(encoding="utf-8") + section = text[: text.index("## [0.2.0]")] + headings = [line for line in section.splitlines() if line.startswith("### ")] + assert headings == [ + "### Breaking changes and migration", + "### Added", + "### Changed", + "### Fixed", + "### Known limitations", + ] + assert "### Changed\n\n- A change. (ITL-7)\n\n### Fixed\n" in section + assert section.endswith("### Known limitations\n\n- A limit. (ITL-7)\n\n") + # The released section is untouched. + assert ( + text[text.index("## [0.2.0]") :] == CHANGELOG[CHANGELOG.index("## [0.2.0]") :] + ) + + +def test_fold_targets_only_the_named_section(workspace: tuple[Path, Path]) -> None: + changelog, fragments = workspace + (fragments / "ITL-7.md").write_text( + "### Changed\n\n- Late. (ITL-7)\n", encoding="utf-8" + ) + + result = _fold(changelog, fragments, version="0.2.0") + + assert result.returncode == 0, result.stderr + text = changelog.read_text(encoding="utf-8") + cut = CHANGELOG.index("## [0.2.0]") + assert text[:cut] == CHANGELOG[:cut] + assert text.endswith("### Changed\n\n- Old changed.\n- Late. (ITL-7)\n") + + +def test_fold_creates_a_missing_release_section_on_top( + workspace: tuple[Path, Path], +) -> None: + changelog, fragments = workspace + (fragments / "ITL-7.md").write_text( + "### Fixed\n\n- A fix. (ITL-7)\n\n### Added\n\n- A thing. (ITL-7)\n", + encoding="utf-8", + ) + + result = _fold(changelog, fragments, version="0.4.0") + + assert result.returncode == 0, result.stderr + assert changelog.read_text(encoding="utf-8") == CHANGELOG.replace( + "## [0.3.0] — unreleased\n", + "## [0.4.0] — unreleased\n\n" + "### Added\n\n- A thing. (ITL-7)\n\n" + "### Fixed\n\n- A fix. (ITL-7)\n\n" + "## [0.3.0] — unreleased\n", + ) + + +def test_fold_does_not_treat_a_code_fence_line_as_a_heading( + workspace: tuple[Path, Path], +) -> None: + changelog, fragments = workspace + changelog.write_text( + CHANGELOG.replace( + "Existing paragraph.\n", + "Existing paragraph.\n\n```text\n### Added\n## [0.2.0]\n```\n", + ), + encoding="utf-8", + ) + (fragments / "ITL-7.md").write_text( + "### Added\n\n- A thing. (ITL-7)\n", encoding="utf-8" + ) + + result = _fold(changelog, fragments) + + assert result.returncode == 0, result.stderr + text = changelog.read_text(encoding="utf-8") + assert " wrapped. (ITL-3)\n- A thing. (ITL-7)\n\n### Fixed\n" in text + assert "```text\n### Added\n## [0.2.0]\n```\n\n### Added\n" in text + + +def test_fold_refuses_and_changes_nothing_when_a_fragment_is_malformed( + workspace: tuple[Path, Path], +) -> None: + changelog, fragments = workspace + (fragments / "ITL-7.md").write_text("### Added\n\n- Thing.\n", encoding="utf-8") + (fragments / "ITL-8.md").write_text("### Nope\n\n- Thing.\n", encoding="utf-8") + + result = _fold(changelog, fragments) + + assert result.returncode == 1 + assert "ITL-8.md" in result.stderr + assert changelog.read_text(encoding="utf-8") == CHANGELOG + assert (fragments / "ITL-7.md").exists() + assert (fragments / "ITL-8.md").exists() + + +def test_fold_with_no_fragments_changes_nothing(workspace: tuple[Path, Path]) -> None: + changelog, fragments = workspace + result = _fold(changelog, fragments) + assert result.returncode == 0, result.stderr + assert changelog.read_text(encoding="utf-8") == CHANGELOG + + +def test_fold_requires_a_version(workspace: tuple[Path, Path]) -> None: + changelog, fragments = workspace + result = _run("--changelog", changelog, "--fragments-dir", fragments) + assert result.returncode != 0 + assert "--version" in result.stderr