From 30963a1ee3a04004203df88654d9f7ce0ac9e4e9 Mon Sep 17 00:00:00 2001
From: allen0099 <s96016641@gmail.com>
Date: Fri, 25 Sep 2026 16:45:57 +0000
Subject: [PATCH] release: list one line per change in the GitHub release notes

The release body used to be the promoted changelog section verbatim. Our
entries explain each change in full, so the 0.3.7 release page was about
8 KB of long bullets. GitHub also renders every hard wrap as a line
break, which made them longer still.

Each changelog entry now opens with a bold one-line summary. The new
release_notes() in scripts/changelog_release.py turns the promoted
section into those summaries plus the issue links found in each entry,
grouped under the same ### headings. It ends with a link to the
version's section on the documentation site's changelog, which keeps the
full entries.

An entry without a summary, or a line that is neither a ### heading nor
a list entry, is an error that names the entries. The release therefore
stops before publishing anything, and so does a dry run. The test that
promotes the real CHANGELOG.md runs the same check, so the pull request
that adds an entry without a summary fails CI instead of the release.

CHANGELOG.md, DEVELOPMENT.md and CONTRIBUTING.md describe the format.
Released versions are left as they are.
---
 .github/workflows/release.yml   |   3 +-
 CHANGELOG.md                    |  18 +++--
 docs/CONTRIBUTING.md            |   9 +--
 docs/DEVELOPMENT.md             |  35 +++++++--
 scripts/changelog_release.py    |  95 ++++++++++++++++++++++--
 tests/test_changelog_release.py | 123 +++++++++++++++++++++++++++++---
 6 files changed, 251 insertions(+), 32 deletions(-)

diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml
index 8ab9e26..48a8540 100644
--- a/.github/workflows/release.yml
+++ b/.github/workflows/release.yml
@@ -150,7 +150,8 @@ jobs:
       # Promoting the changelog is part of cutting the release, not a chore to
       # remember afterwards: the script fails when `## [Unreleased]` is empty,
       # so a release with nothing written down stops here instead of shipping
-      # release notes that say nothing.
+      # release notes that say nothing. It also fails when an entry has no bold
+      # one-line summary, because the release notes are those summaries.
       - name: Promote the changelog
         env:
           VERSION: ${{ steps.version.outputs.version }}
diff --git a/CHANGELOG.md b/CHANGELOG.md
index a960843..afeadfe 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -6,15 +6,25 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 This file records what changed for users of the library, in particular
-behaviour that changed under an unchanged API. The `## [Unreleased]` section is
-what the Release workflow publishes as the GitHub release notes, and a release
-with an empty one fails — so entries are added by hand, in the pull request
-that earns them. See [Releasing](https://fastapi-cachex.readthedocs.io/en/latest/DEVELOPMENT/#releasing).
+behaviour that changed under an unchanged API. Entries are added by hand, in
+the pull request that earns them, and each one opens with a bold one-line
+summary: `- **What changed.** The details...`. The GitHub release notes list
+those summaries and link back here, and a release fails if `## [Unreleased]`
+is empty or an entry has no summary. Entries before 0.3.8 predate this format.
+See [Releasing](https://fastapi-cachex.readthedocs.io/en/latest/DEVELOPMENT/#releasing).
 
 Note that 0.3.3 was never released; 0.3.4 follows 0.3.2.
 
 ## [Unreleased]
 
+### Changed
+
+- **GitHub release notes list one line per change.** Each changelog entry now
+  opens with a bold one-line summary. The release page shows only those
+  summaries with their issue links, grouped as in the changelog, and links to
+  the full entries on the documentation site. The changelog itself keeps the
+  details.
+
 ## [0.3.7] - 2026-09-25
 
 ### Added
diff --git a/docs/CONTRIBUTING.md b/docs/CONTRIBUTING.md
index 1e7da2d..cefe2f6 100644
--- a/docs/CONTRIBUTING.md
+++ b/docs/CONTRIBUTING.md
@@ -34,10 +34,11 @@ Please refer to our [Development Guide](DEVELOPMENT.md) for detailed instruction
    is allowed to lag behind them
 2. Add an entry to the `## [Unreleased]` section of
    [CHANGELOG.md](https://github.com/allen0099/FastAPI-CacheX/blob/master/CHANGELOG.md) if your change alters behaviour, adds public
-   API, or fixes something a user could have hit. That section is what the
-   release notes are built from, and a release refuses to run on an empty one,
-   so an omission surfaces — but only at release time, and only as "somebody
-   forgot", never as which PR it was
+   API, or fixes something a user could have hit. Open the entry with a bold
+   one-line summary, `- **What changed.** The details...`: the release notes
+   list only those summaries, and CI fails on an entry without one. A release
+   also refuses to run on an empty section, so an omission surfaces — but only
+   at release time, and only as "somebody forgot", never as which PR it was
 3. Update the documentation with any new dependencies, features, or changes.
    New public API needs a docstring and, if it lives in a module not yet
    covered, an entry under `docs/api/`; check the site with
diff --git a/docs/DEVELOPMENT.md b/docs/DEVELOPMENT.md
index f3c45df..0d43f68 100644
--- a/docs/DEVELOPMENT.md
+++ b/docs/DEVELOPMENT.md
@@ -262,8 +262,9 @@ The workflow runs in this order:
    `vX.Y.Z` is already tagged, locally or on the remote, the run stops here.
 3. **The changelog.** `scripts/changelog_release.py` renames `## [Unreleased]`
    to `## [X.Y.Z] - YYYY-MM-DD`, opens a fresh empty `## [Unreleased]` above
-   it, rewrites the compare links at the bottom, and writes the promoted
-   section out to be used as the release body.
+   it, rewrites the compare links at the bottom, and writes the release body:
+   each entry's bold summary and issue links, and a link to the full entries
+   on the documentation site.
 4. **The permanent part**, kept together at the end: commit the version bump
    and the promoted changelog, push it, tag, push the tag by refspec, create
    the GitHub release from the promoted section, publish to PyPI.
@@ -295,10 +296,32 @@ different path, not of this one.
 `CHANGELOG.md` used to be maintained entirely by hand and nothing enforced it:
 the release notes came from `git log --pretty=format:"- %s (%h)"`, so a release
 happened whether or not anyone had written down what it meant. That is no
-longer true. The release body **is** the `## [Unreleased]` section, and an
-empty one fails the run — for a hand-maintained file, "nobody wrote it down" is
-far more likely than "nothing changed". The commit list has not been lost: the
-release body ends with a compare link against the previous tag.
+longer true. The release body is built from the `## [Unreleased]` section, and
+an empty one fails the run — for a hand-maintained file, "nobody wrote it down"
+is far more likely than "nothing changed". The commit list has not been lost:
+the release body ends with a compare link against the previous tag.
+
+The changelog and the release page serve different readers. The changelog
+explains each change in full: what behaviour moved, why, and how to adapt. The
+release page is scanned, so it gets one line per change. Every entry therefore
+opens with a bold summary, and the release body is just those summaries:
+
+```markdown
+- **Add `CacheManager.add()` for store-if-absent writes.** It uses the same
+  key prefix, JSON encoding and `default_ttl` as `set()`, and runs on the
+  backend's atomic `set_if_absent` ... ([#65](https://github.com/allen0099/FastAPI-CacheX/issues/65))
+```
+
+becomes ``- Add `CacheManager.add()` for store-if-absent writes. ([#65](...))``
+under the same `### Added` heading. The issue links are carried over from
+anywhere in the entry, and the body ends with a link to the version's section
+on the documentation site's changelog page. Write the summary for someone
+deciding whether this release matters to them: what changed, in the imperative
+or as a plain statement, not how. An entry without one fails the run and is
+named in the error, and so does a line in the section that is neither a `###`
+heading nor a `- ` entry. `tests/test_changelog_release.py` runs the same check
+on the real `CHANGELOG.md`, so the pull request that adds an entry without a
+summary fails CI instead of the release.
 
 Two details of the promotion are worth knowing, because both have bitten this
 project:
diff --git a/scripts/changelog_release.py b/scripts/changelog_release.py
index e182267..9e80795 100644
--- a/scripts/changelog_release.py
+++ b/scripts/changelog_release.py
@@ -2,10 +2,20 @@
 
 `release.yml` calls this so that one manual dispatch does the whole cut: the
 heading is renamed, a fresh empty `## [Unreleased]` is opened above it, the
-compare links at the bottom are rewritten, and the promoted section is written
-out to be used verbatim as the GitHub release body.
+compare links at the bottom are rewritten, and a short version of the promoted
+section is written out as the GitHub release body.
 
-Two rules drive the implementation:
+The changelog keeps the full story of each change; the release page lists one
+line per change. Every entry therefore opens with a bold one-line summary::
+
+    - **Add `CacheManager.add()` for store-if-absent writes.** It uses the
+      same key prefix ... ([#65](https://github.com/.../issues/65))
+
+and the release body is those summaries with their issue links, grouped under
+the same `###` headings, followed by a link to the full entries on the
+documentation site.
+
+Three rules drive the implementation:
 
 * The previous version is **read from the existing headings**, never derived
   from the new one. 0.3.3 was never released, so `[0.3.4]` has to compare
@@ -14,6 +24,8 @@
 * An empty `## [Unreleased]` is an error, not an empty release note. The
   changelog is maintained by hand, so "nothing was written down" and "nothing
   changed" look identical from here, and only the former is likely.
+* An entry without a bold summary is an error too, for the same reason: the
+  release would otherwise publish a line nobody chose.
 
 Run it directly to see what a release would produce::
 
@@ -36,6 +48,12 @@
 )
 _LINK = re.compile(r"^\[(?P<label>[^\]]+)\]: (?P<url>\S+)[ \t]*$", re.MULTILINE)
 _VERSION = re.compile(r"^\d+\.\d+\.\d+$")
+_SUMMARY = re.compile(r"^\*\*(?P<summary>.+?)\*\*", re.DOTALL)
+_ISSUE_LINK = re.compile(r"\(\[#\d+\]\([^)\s]+\)(?:, \[#\d+\]\([^)\s]+\))*\)")
+
+# Where the full entries are read. `stable` is rebuilt from the tag a release
+# pushes, and the anchor is the one the site generates for `## [X.Y.Z] - DATE`.
+DOCS_CHANGELOG = "https://fastapi-cachex.readthedocs.io/en/stable/changelog/"
 
 
 class ChangelogError(RuntimeError):
@@ -134,6 +152,70 @@ def promote(text: str, version: str, date: str) -> tuple[str, str]:
     return rewritten, body.strip() + "\n"
 
 
+def _entries(body: str) -> list[tuple[str, str]]:
+    """Split a changelog section into `(### heading, entry text)` pairs.
+
+    An entry is a top-level `- ` bullet with everything indented under it,
+    nested lists included. Entries above the first heading get `""`.
+    """
+    entries: list[tuple[str, list[str]]] = []
+    heading = ""
+    for line in body.splitlines():
+        if line.startswith("### "):
+            heading = line
+        elif line.startswith("- "):
+            entries.append((heading, [line[2:]]))
+        elif line.strip() and not line[0].isspace():
+            msg = f"`{line}` is neither a `###` heading nor a `- ` list entry"
+            raise ChangelogError(msg)
+        elif entries and entries[-1][0] == heading:
+            entries[-1][1].append(line.strip())
+    return [(section, " ".join(filter(None, lines))) for section, lines in entries]
+
+
+def release_notes(body: str, version: str, date: str) -> str:
+    """Shorten a promoted section to one line per entry, for the release page.
+
+    Args:
+        body: The promoted section, as returned by `promote`.
+        version: The version being released.
+        date: The release date, `YYYY-MM-DD`.
+
+    Returns:
+        Each entry's bold summary and issue links, under the section's `###`
+        headings, then a link to the full entries on the documentation site.
+
+    Raises:
+        ChangelogError: A line is neither a heading nor an entry, or an entry
+            does not open with a bold summary.
+    """
+    lines: list[str] = []
+    missing: list[str] = []
+    heading = ""
+    for section, text in _entries(body):
+        summary = _SUMMARY.match(text)
+        if summary is None:
+            missing.append(text[:70])
+            continue
+        if section != heading:
+            heading = section
+            lines += ["", heading, ""] if lines else [heading, ""]
+        links = " ".join(_ISSUE_LINK.findall(text))
+        line = " ".join(summary["summary"].split())
+        lines.append(f"- {line} {links}".rstrip())
+    if missing:
+        listed = "\n".join(f"  - {text}..." for text in missing)
+        msg = (
+            "every changelog entry must open with a bold one-line summary, "
+            "`- **What changed.** Details...`; these do not:\n" + listed
+        )
+        raise ChangelogError(msg)
+
+    anchor = f"{version.replace('.', '')}-{date}"
+    lines += ["", f"**Full changelog**: {DOCS_CHANGELOG}#{anchor}"]
+    return "\n".join(lines) + "\n"
+
+
 def _today() -> str:
     return datetime.datetime.now(tz=datetime.timezone.utc).date().isoformat()
 
@@ -151,7 +233,7 @@ def _parse_args(argv: list[str] | None) -> argparse.Namespace:
     parser.add_argument(
         "--release-notes",
         type=Path,
-        help="write the promoted section here, for use as the release body",
+        help="write the release body (one line per entry) here",
     )
     parser.add_argument(
         "--dry-run",
@@ -170,17 +252,18 @@ def main(argv: list[str] | None = None) -> int:
             args.version,
             args.date,
         )
+        notes = release_notes(body, args.version, args.date)
     except (ChangelogError, OSError) as error:
         print(f"error: {error}", file=sys.stderr)  # noqa: T201
         return 1
 
     if args.dry_run:
-        print(body, end="")  # noqa: T201
+        print(notes, end="")  # noqa: T201
         return 0
 
     args.changelog.write_text(rewritten, encoding="utf-8")
     if args.release_notes is not None:
-        args.release_notes.write_text(body, encoding="utf-8")
+        args.release_notes.write_text(notes, encoding="utf-8")
     return 0
 
 
diff --git a/tests/test_changelog_release.py b/tests/test_changelog_release.py
index e0ec75c..a563fb9 100644
--- a/tests/test_changelog_release.py
+++ b/tests/test_changelog_release.py
@@ -10,8 +10,15 @@
 from scripts.changelog_release import ChangelogError
 from scripts.changelog_release import main
 from scripts.changelog_release import promote
+from scripts.changelog_release import release_notes
 
 BASE = "https://github.com/allen0099/FastAPI-CacheX"
+ENTRY = f"- **A thing.** With the details. ([#1]({BASE}/issues/1))"
+NOTES = (
+    f"### Added\n\n- A thing. ([#1]({BASE}/issues/1))\n\n"
+    "**Full changelog**: "
+    "https://fastapi-cachex.readthedocs.io/en/stable/changelog/#035-2026-09-14\n"
+)
 
 CHANGELOG = f"""# Changelog
 
@@ -19,7 +26,7 @@
 
 ### Added
 
-- A thing.
+{ENTRY}
 
 ## [0.3.4] - 2026-09-05
 
@@ -63,7 +70,7 @@ def test_promote_rewrites_the_compare_links():
 def test_promote_returns_only_the_unreleased_section_as_the_release_body():
     _, body = promote(CHANGELOG, "0.3.5", "2026-09-14")
 
-    assert body == "### Added\n\n- A thing.\n"
+    assert body == f"### Added\n\n{ENTRY}\n"
     assert "older thing" not in body
 
 
@@ -106,9 +113,7 @@ def test_the_first_release_links_to_the_tag_instead_of_a_comparison():
 
 def test_version_numbers_in_prose_are_left_alone():
     """Only headings and link definitions are rewritten."""
-    prose = CHANGELOG.replace(
-        "- A thing.", "- `X` is deprecated and goes away in 0.3.5."
-    )
+    prose = CHANGELOG.replace(ENTRY, "- `X` is deprecated and goes away in 0.3.5.")
 
     rewritten, body = promote(prose, "0.3.5", "2026-09-14")
 
@@ -117,7 +122,7 @@ def test_version_numbers_in_prose_are_left_alone():
 
 
 def test_an_empty_unreleased_section_is_an_error():
-    empty = CHANGELOG.replace("### Added\n\n- A thing.\n", "")
+    empty = CHANGELOG.replace(f"### Added\n\n{ENTRY}\n", "")
 
     with pytest.raises(ChangelogError, match="is empty"):
         promote(empty, "0.3.5", "2026-09-14")
@@ -178,7 +183,7 @@ def test_the_repository_changelog_can_be_released():
     # rightly refuses. Give it an entry so the rest of the file is still checked.
     text = re.sub(
         r"^## \[Unreleased\]\n\s*(?=^## \[)",
-        "## [Unreleased]\n\n### Fixed\n\n- Placeholder entry.\n\n",
+        "## [Unreleased]\n\n### Fixed\n\n- **Placeholder entry.**\n\n",
         text,
         count=1,
         flags=re.MULTILINE,
@@ -190,6 +195,8 @@ def test_the_repository_changelog_can_be_released():
     assert text.count("removed in 0.3.5") == rewritten.count("removed in 0.3.5")
     assert f"[0.9.9]: {BASE}/compare/v{latest[1]}...v0.9.9" in rewritten
     assert body.startswith("### ")
+    # Every entry waiting in `Unreleased` has the summary the release page needs.
+    assert release_notes(body, "0.9.9", "2026-09-14").startswith("### ")
     # Every released heading still has a link definition, and vice versa.
     headings = {
         line.removeprefix("## [").split("]")[0]
@@ -220,7 +227,7 @@ def test_main_writes_the_changelog_and_the_release_notes(tmp_path: Path):
 
     assert exit_code == 0
     assert "## [0.3.5] - 2026-09-14" in changelog.read_text(encoding="utf-8")
-    assert notes.read_text(encoding="utf-8") == "### Added\n\n- A thing.\n"
+    assert notes.read_text(encoding="utf-8") == NOTES
 
 
 def test_main_dry_run_changes_nothing(
@@ -229,10 +236,20 @@ def test_main_dry_run_changes_nothing(
     changelog = tmp_path / "CHANGELOG.md"
     changelog.write_text(CHANGELOG, encoding="utf-8")
 
-    exit_code = main(["--version", "0.3.5", "--changelog", str(changelog), "--dry-run"])
+    exit_code = main(
+        [
+            "--version",
+            "0.3.5",
+            "--date",
+            "2026-09-14",
+            "--changelog",
+            str(changelog),
+            "--dry-run",
+        ]
+    )
 
     assert exit_code == 0
-    assert capsys.readouterr().out == "### Added\n\n- A thing.\n"
+    assert capsys.readouterr().out == NOTES
     assert changelog.read_text(encoding="utf-8") == CHANGELOG
 
 
@@ -253,7 +270,7 @@ def test_main_reports_the_reason_and_fails(
 ):
     changelog = tmp_path / "CHANGELOG.md"
     changelog.write_text(
-        CHANGELOG.replace("### Added\n\n- A thing.\n", ""), encoding="utf-8"
+        CHANGELOG.replace(f"### Added\n\n{ENTRY}\n", ""), encoding="utf-8"
     )
 
     exit_code = main(["--version", "0.3.5", "--changelog", str(changelog)])
@@ -281,3 +298,87 @@ def test_a_second_release_cannot_open_a_second_unreleased():
 
     with pytest.raises(ChangelogError, match="is empty"):
         promote(rewritten, "0.3.6", "2026-09-15")
+
+
+def test_release_notes_keep_one_line_per_entry_under_its_heading():
+    body = f"""### Added
+
+- **Add `x()` for doing X.** It does X by way of Y, which takes a long
+  explanation over several lines. ([#10]({BASE}/issues/10))
+- **Add `y()`.** No issue for this one.
+
+### Fixed
+
+- **Stop `z()` from
+  losing entries.** The summary above wraps; the details carry a list:
+  - a first detail with a [link](https://example.com);
+  - a second detail.
+
+  ([#11]({BASE}/issues/11), [#12]({BASE}/pull/12))
+"""
+    notes = release_notes(body, "1.2.3", "2026-10-01")
+
+    assert notes == (
+        "### Added\n\n"
+        f"- Add `x()` for doing X. ([#10]({BASE}/issues/10))\n"
+        "- Add `y()`.\n\n"
+        "### Fixed\n\n"
+        f"- Stop `z()` from losing entries. ([#11]({BASE}/issues/11), [#12]({BASE}/pull/12))\n\n"
+        "**Full changelog**: "
+        "https://fastapi-cachex.readthedocs.io/en/stable/changelog/#123-2026-10-01\n"
+    )
+
+
+def test_release_notes_list_every_entry_without_a_summary():
+    body = """### Added
+
+- **Has one.** Details.
+- Has none, so the release would publish this whole sentence.
+
+### Fixed
+
+- `thing()` works now.
+"""
+    with pytest.raises(ChangelogError, match="bold one-line summary") as error:
+        release_notes(body, "1.2.3", "2026-10-01")
+
+    assert "Has none, so the release" in str(error.value)
+    assert "`thing()` works now." in str(error.value)
+    assert "Has one." not in str(error.value)
+
+
+def test_release_notes_reject_text_that_is_not_an_entry():
+    body = "### Added\n\nA paragraph instead of a list.\n"
+
+    with pytest.raises(ChangelogError, match="neither a `###` heading"):
+        release_notes(body, "1.2.3", "2026-10-01")
+
+
+def test_release_notes_accept_entries_before_any_heading():
+    notes = release_notes("- **Loose entry.** Details.\n", "1.2.3", "2026-10-01")
+
+    assert notes.startswith("- Loose entry.\n\n**Full changelog**: ")
+
+
+def test_main_refuses_to_release_an_entry_without_a_summary(
+    tmp_path: Path, capsys: pytest.CaptureFixture[str]
+):
+    changelog = tmp_path / "CHANGELOG.md"
+    changelog.write_text(CHANGELOG.replace(ENTRY, "- A thing."), encoding="utf-8")
+    notes = tmp_path / "release-notes.md"
+
+    exit_code = main(
+        [
+            "--version",
+            "0.3.5",
+            "--changelog",
+            str(changelog),
+            "--release-notes",
+            str(notes),
+        ]
+    )
+
+    assert exit_code == 1
+    assert "bold one-line summary" in capsys.readouterr().err
+    assert "## [0.3.5]" not in changelog.read_text(encoding="utf-8")
+    assert not notes.exists()