From f39fc8e4ec9392018642fb4abf7787f75c8dc225 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Lars=20Gr=C3=BCter?= <lagru@mailbox.org>
Date: Mon, 13 Nov 2023 19:38:01 +0100
Subject: [PATCH 01/16] Uncouple PRs and summaries with new ChangeNote class

The new dataclass ChangeNote helps with uncoupling the `_query.py` logic
and the `_format.py` logic from each other somewhat. In this case
one pull request can be turned into multiple change notes which might
appear in separate sections. This optional behavior allows to deal with
somewhat large or unfocused pull requests.

Long-term this step would also be necessary in case PyGitHub is replaced
with a GraphQl-based approach.
---
 README.md                          |  12 ++-
 src/changelist/_cli.py             |  10 ++-
 src/changelist/_format.py          | 132 +++++++++++++++++++----------
 src/changelist/default_config.toml |  12 ++-
 4 files changed, 111 insertions(+), 55 deletions(-)

diff --git a/README.md b/README.md
index 270196a..38b401a 100644
--- a/README.md
+++ b/README.md
@@ -83,17 +83,21 @@ ignored_user_logins = [
 ]
 
 # If this regex matches a pull requests description, the captured content
-# is included instead of the pull request title.
+# is included instead of the pull request title. The regex is allowed to match
+# more than once in which case a single pull request may result in multiple
+# items. Each summary can optionally be prefixed with a `Label:` which takes
+# precedence over the pull requests labels. This is useful if one pull request
+# should be summarized in different sections.
 # E.g. the default regex below is matched by
 #
 # ```release-note
-# An ideally expressive description of the change that is included as a single
-# bullet point. Newlines are removed.
+# Label: An ideally expressive description of the change that is included as
+# a single bullet point. Newlines are removed.
 # ```
 #
 # If you modify this regex, make sure to match the content with a capture
 # group named "summary".
-pr_summary_regex = "^```release-note\\s*(?P<summary>[\\s\\S]*?\\w[\\s\\S]*?)\\s*^```"
+pr_summary_regex = "^```release-note\\s*((?P<label>[^:]*):)?(?P<summary>[\\s\\S]*?\\w[\\s\\S]*?)\\s*^```"
 
 # If any of a pull request's labels matches one of the regexes on the left side
 # its summary will appear in the appropriate section with the title given on
diff --git a/src/changelist/_cli.py b/src/changelist/_cli.py
index 5e2070a..9944199 100644
--- a/src/changelist/_cli.py
+++ b/src/changelist/_cli.py
@@ -12,7 +12,7 @@
 from tqdm import tqdm
 
 from ._config import add_config_defaults, local_config, remote_config
-from ._format import MdFormatter, RstFormatter
+from ._format import ChangeNote, MdFormatter, RstFormatter
 from ._query import commits_between, contributors, pull_requests_from_commits
 
 logger = logging.getLogger(__name__)
@@ -152,10 +152,15 @@ def main(
         pull_requests=lazy_tqdm(pull_requests, desc="Fetching reviewers"),
     )
 
+    change_notes = ChangeNote.from_pull_requests(
+        pull_requests,
+        pr_summary_regex=re.compile(config["pr_summary_regex"], flags=re.MULTILINE),
+    )
+
     Formatter = {"md": MdFormatter, "rst": RstFormatter}[format]
     formatter = Formatter(
         repo_name=org_repo.split("/")[-1],
-        pull_requests=pull_requests,
+        change_notes=change_notes,
         authors=authors,
         reviewers=reviewers,
         version=version,
@@ -163,7 +168,6 @@ def main(
         intro_template=config["intro_template"],
         outro_template=config["outro_template"],
         label_section_map=config["label_section_map"],
-        pr_summary_regex=re.compile(config["pr_summary_regex"], flags=re.MULTILINE),
         ignored_user_logins=config["ignored_user_logins"],
     )
 
diff --git a/src/changelist/_format.py b/src/changelist/_format.py
index c198152..fe550de 100644
--- a/src/changelist/_format.py
+++ b/src/changelist/_format.py
@@ -3,7 +3,7 @@
 from collections import OrderedDict
 from collections.abc import Iterable
 from dataclasses import dataclass
-from typing import Union
+from datetime import datetime
 
 from github.NamedUser import NamedUser
 from github.PullRequest import PullRequest
@@ -11,13 +11,67 @@
 logger = logging.getLogger(__name__)
 
 
+@dataclass(frozen=True, slots=True, kw_only=True)
+class ChangeNote:
+    """Describes an atomic change in the notes."""
+
+    content: str
+    reference_name: str
+    reference_url: str
+    labels: tuple[str, ...]
+    timestamp: datetime
+
+    @classmethod
+    def from_pull_requests(
+        cls,
+        pull_requests: set[PullRequest],
+        *,
+        pr_summary_regex: re.Pattern,
+    ) -> "set[ChangeNote]":
+        """Create a set of notes from pull requests.
+
+        Create one or more notes describing an atomic change from each given
+        pull request.
+
+        `pr_summary_regex` is used to detect one or multiple  notes in a pull
+        request description that will be used instead of the pull request title
+        if present. This uncouples pull requests and notes somewhat. While
+        ideally, a pull request introduces a change that would be described in
+        a single note, this is often not the case.
+        """
+        notes = set()
+        for pr in pull_requests:
+            if not pr.body or not (
+                matches := tuple(pr_summary_regex.finditer(pr.body))
+            ):
+                logger.debug("falling back to title for %s", pr.html_url)
+                matches = ({"summary": pr.title, "label": None},)
+            assert len(matches) >= 1
+            for match in matches:
+                summary = match["summary"]
+                if match["label"] is not None:
+                    labels = (match["label"],)
+                else:
+                    labels = tuple(label.name for label in pr.labels)
+                notes.add(
+                    cls(
+                        content=summary.strip(),
+                        reference_name=f"#{pr.number}",
+                        reference_url=pr.html_url,
+                        labels=labels,
+                        timestamp=pr.merged_at,
+                    )
+                )
+        return notes
+
+
 @dataclass(frozen=True, kw_only=True)
 class MdFormatter:
     """Format release notes in Markdown from PRs, authors and reviewers."""
 
     repo_name: str
-    pull_requests: set[PullRequest]
-    authors: set[Union[NamedUser]]
+    change_notes: set[ChangeNote]
+    authors: set[NamedUser]
     reviewers: set[NamedUser]
 
     version: str
@@ -27,8 +81,8 @@ class MdFormatter:
 
     # Associate regexes matching PR labels to a section titles in the release notes
     label_section_map: dict[str, str]
-    pr_summary_regex: re.Pattern
-    ignored_user_logins: tuple[str]
+
+    ignored_user_logins: tuple[str, ...]
 
     def __str__(self) -> str:
         """Return complete release notes document as a string."""
@@ -51,45 +105,42 @@ def iter_lines(self) -> Iterable[str]:
         yield from self._format_section_title(title, level=1)
         yield "\n"
         yield from self._format_intro()
-        for title, pull_requests in self._prs_by_section.items():
-            yield from self._format_pr_section(title, pull_requests)
+        for title, notes in self._notes_by_section.items():
+            yield from self._format_change_section(title, notes)
         yield from self._format_contributor_section(self.authors, self.reviewers)
         yield from self._format_outro()
 
     @property
-    def _prs_by_section(self) -> OrderedDict[str, set[PullRequest]]:
-        """Map pull requests to section titles.
-
-        Pull requests whose labels do not match one of the sections given in
-        `regex_section_map`, are sorted into a section named "Other".
-        """
+    def _notes_by_section(self) -> OrderedDict[str, set[ChangeNote]]:
+        """Map change notes to section titles."""
         label_section_map = {
-            re.compile(pattern): section_name
+            re.compile(pattern, flags=re.IGNORECASE): section_name
             for pattern, section_name in self.label_section_map.items()
         }
-        prs_by_section = OrderedDict()
+
+        notes_by_section = OrderedDict()
         for _, section_name in self.label_section_map.items():
-            prs_by_section[section_name] = set()
-        prs_by_section["Other"] = set()
+            notes_by_section[section_name] = set()
+        notes_by_section["Other"] = set()
 
-        for pr in self.pull_requests:
+        for note in self.change_notes:
             matching_sections = [
                 section_name
                 for regex, section_name in label_section_map.items()
-                if any(regex.match(label.name) for label in pr.labels)
+                if any(regex.match(label) for label in note.labels)
             ]
             for section_name in matching_sections:
-                prs_by_section[section_name].add(pr)
+                notes_by_section[section_name].add(note)
             if not matching_sections:
                 logger.warning(
                     "%s without matching label, sorting into section 'Other'",
-                    pr.html_url,
+                    note.reference_url,
                 )
-                prs_by_section["Other"].add(pr)
-
-        return prs_by_section
+                notes_by_section["Other"].add(note)
+        return notes_by_section
 
     def _sanitize_text(self, text: str) -> str:
+        """Remove newlines and strip whitespace."""
         text = text.strip()
         text = text.replace("\r\n", " ")
         text = text.replace("\n", " ")
@@ -101,34 +152,26 @@ def _format_link(self, name: str, target: str) -> str:
     def _format_section_title(self, title: str, *, level: int) -> Iterable[str]:
         yield f"{'#' * level} {title}\n"
 
-    def _parse_pull_request_summary(self, pr: PullRequest) -> str:
-        if pr.body and (match := self.pr_summary_regex.search(pr.body)):
-            summary = match["summary"]
-        else:
-            logger.debug("falling back to title for %s", pr.html_url)
-            summary = pr.title
-        summary = self._sanitize_text(summary)
-        return summary
-
-    def _format_pull_request(self, pr: PullRequest) -> Iterable[str]:
-        link = self._format_link(f"#{pr.number}", f"{pr.html_url}")
-        summary = self._parse_pull_request_summary(pr).rstrip(".")
+    def _format_change_note(self, note: ChangeNote) -> Iterable[str]:
+        """Format a note about an atomic change."""
+        link = self._format_link(note.reference_name, note.reference_url)
+        summary = self._sanitize_text(note.content).rstrip(".")
         summary = f"- {summary} ({link}).\n"
         yield summary
 
-    def _format_pr_section(
-        self, title: str, pull_requests: set[PullRequest]
+    def _format_change_section(
+        self, title: str, notes: set[ChangeNote]
     ) -> Iterable[str]:
-        """Format a section title and list its pull requests sorted by merge date."""
-        if pull_requests:
+        """Format a section title and list its items sorted by merge date."""
+        if notes:
             yield from self._format_section_title(title, level=2)
             yield "\n"
 
-            for pr in sorted(pull_requests, key=lambda pr: pr.merged_at):
-                yield from self._format_pull_request(pr)
+            for item in sorted(notes, key=lambda note: note.timestamp):
+                yield from self._format_change_note(item)
             yield "\n"
 
-    def _format_user_line(self, user: Union[NamedUser]) -> str:
+    def _format_user_line(self, user: NamedUser) -> str:
         line = f"@{user.login}"
         line = self._format_link(line, user.html_url)
         if user.name:
@@ -137,7 +180,7 @@ def _format_user_line(self, user: Union[NamedUser]) -> str:
 
     def _format_contributor_section(
         self,
-        authors: set[Union[NamedUser]],
+        authors: set[NamedUser],
         reviewers: set[NamedUser],
     ) -> Iterable[str]:
         """Format contributor section and list users sorted by login handle."""
@@ -178,6 +221,7 @@ class RstFormatter(MdFormatter):
     """Format release notes in reStructuredText from PRs, authors and reviewers."""
 
     def _sanitize_text(self, text) -> str:
+        """Remove newlines, strip whitespace and convert literals to rST syntax."""
         text = super()._sanitize_text(text)
         text = text.replace("`", "``")
         return text
diff --git a/src/changelist/default_config.toml b/src/changelist/default_config.toml
index 5e1d939..2083549 100644
--- a/src/changelist/default_config.toml
+++ b/src/changelist/default_config.toml
@@ -27,17 +27,21 @@ ignored_user_logins = [
 ]
 
 # If this regex matches a pull requests description, the captured content
-# is included instead of the pull request title.
+# is included instead of the pull request title. The regex is allowed to match
+# more than once in which case a single pull request may result in multiple
+# items. Each summary can optionally be prefixed with a `Label:` which takes
+# precedence over the pull requests labels. This is useful if one pull request
+# should be summarized in different sections.
 # E.g. the default regex below is matched by
 #
 # ```release-note
-# An ideally expressive description of the change that is included as a single
-# bullet point. Newlines are removed.
+# Label: An ideally expressive description of the change that is included as
+# a single bullet point. Newlines are removed.
 # ```
 #
 # If you modify this regex, make sure to match the content with a capture
 # group named "summary".
-pr_summary_regex = "^```release-note\\s*(?P<summary>[\\s\\S]*?\\w[\\s\\S]*?)\\s*^```"
+pr_summary_regex = "^```release-note\\s*((?P<label>[^:]*):)?(?P<summary>[\\s\\S]*?\\w[\\s\\S]*?)\\s*^```"
 
 # If any of a pull request's labels matches one of the regexes on the left side
 # its summary will appear in the appropriate section with the title given on

From 043d0ca1356859e22d7ca453d8c8fdfebf709beb Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Lars=20Gr=C3=BCter?= <lagru@mailbox.org>
Date: Mon, 13 Nov 2023 19:41:27 +0100
Subject: [PATCH 02/16] Uncouple PRs and summaries with new Contributor class

The new dataclass Contributor helps with uncoupling the `_query.py` logic
and the `_format.py` logic from each other somewhat.

Long-term this step would also be necessary in case PyGitHub is replaced
with a GraphQl-based approach.
---
 src/changelist/_cli.py    |  6 ++--
 src/changelist/_format.py | 59 ++++++++++++++++++++++++++++++---------
 2 files changed, 49 insertions(+), 16 deletions(-)

diff --git a/src/changelist/_cli.py b/src/changelist/_cli.py
index 9944199..bdafcde 100644
--- a/src/changelist/_cli.py
+++ b/src/changelist/_cli.py
@@ -12,7 +12,7 @@
 from tqdm import tqdm
 
 from ._config import add_config_defaults, local_config, remote_config
-from ._format import ChangeNote, MdFormatter, RstFormatter
+from ._format import ChangeNote, Contributor, MdFormatter, RstFormatter
 from ._query import commits_between, contributors, pull_requests_from_commits
 
 logger = logging.getLogger(__name__)
@@ -161,8 +161,8 @@ def main(
     formatter = Formatter(
         repo_name=org_repo.split("/")[-1],
         change_notes=change_notes,
-        authors=authors,
-        reviewers=reviewers,
+        authors=Contributor.from_named_users(authors),
+        reviewers=Contributor.from_named_users(reviewers),
         version=version,
         title_template=config["title_template"],
         intro_template=config["intro_template"],
diff --git a/src/changelist/_format.py b/src/changelist/_format.py
index fe550de..ea6a6d2 100644
--- a/src/changelist/_format.py
+++ b/src/changelist/_format.py
@@ -65,14 +65,47 @@ def from_pull_requests(
         return notes
 
 
+@dataclass(frozen=True, slots=True, kw_only=True)
+class Contributor:
+    """A person mentioned in the notes as an author or reviewer.
+
+    `login` should be the GitHub  handle without "@". The "@" is added by the
+    `reference_name` property. `reference_url` is typically a URL to the
+     contributor's GitHub profile.
+    """
+
+    name: str | None
+    login: str
+    reference_url: str
+
+    @property
+    def reference_name(self) -> str:
+        """The GitHub login handle with prefixed "@"."""
+        return f"@{self.login}"
+
+    @classmethod
+    def from_named_users(cls, named_users: set[NamedUser]) -> "set[Contributor]":
+        """ """
+        contributors = set()
+        for user in named_users:
+            contributors.add(
+                cls(
+                    name=user.name,
+                    login=user.login,
+                    reference_url=user.html_url,
+                )
+            )
+        return contributors
+
+
 @dataclass(frozen=True, kw_only=True)
 class MdFormatter:
     """Format release notes in Markdown from PRs, authors and reviewers."""
 
     repo_name: str
     change_notes: set[ChangeNote]
-    authors: set[NamedUser]
-    reviewers: set[NamedUser]
+    authors: set[Contributor]
+    reviewers: set[Contributor]
 
     version: str
     title_template: str
@@ -171,34 +204,34 @@ def _format_change_section(
                 yield from self._format_change_note(item)
             yield "\n"
 
-    def _format_user_line(self, user: NamedUser) -> str:
-        line = f"@{user.login}"
-        line = self._format_link(line, user.html_url)
-        if user.name:
-            line = f"{user.name} ({line})"
+    def _format_contributor_line(self, contributor: Contributor) -> str:
+        line = contributor.reference_name
+        line = self._format_link(line, contributor.reference_url)
+        if contributor.name:
+            line = f"{contributor.name} ({line})"
         return f"- {line}\n"
 
     def _format_contributor_section(
         self,
-        authors: set[NamedUser],
-        reviewers: set[NamedUser],
+        authors: set[Contributor],
+        reviewers: set[Contributor],
     ) -> Iterable[str]:
         """Format contributor section and list users sorted by login handle."""
-        authors = {u for u in authors if u.login not in self.ignored_user_logins}
-        reviewers = {u for u in reviewers if u.login not in self.ignored_user_logins}
+        authors = {c for c in authors if c.login not in self.ignored_user_logins}
+        reviewers = {c for c in reviewers if c.login not in self.ignored_user_logins}
 
         yield from self._format_section_title("Contributors", level=2)
         yield "\n"
 
         yield f"{len(authors)} authors added to this release (alphabetically):\n"
         yield "\n"
-        author_lines = map(self._format_user_line, authors)
+        author_lines = map(self._format_contributor_line, authors)
         yield from sorted(author_lines, key=lambda s: s.lower())
         yield "\n"
 
         yield f"{len(reviewers)} reviewers added to this release (alphabetically):\n"
         yield "\n"
-        reviewers_lines = map(self._format_user_line, reviewers)
+        reviewers_lines = map(self._format_contributor_line, reviewers)
         yield from sorted(reviewers_lines, key=lambda s: s.lower())
         yield "\n"
 

From 72e88ce854af905f16ba2a78d9e536c14009f041 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Lars=20Gr=C3=BCter?= <lagru@mailbox.org>
Date: Mon, 13 Nov 2023 19:43:20 +0100
Subject: [PATCH 03/16] Print notes to stdout after potential warnings

Querying and formatting might generate warnings. Make sure that these
are printed before the generated notes.
---
 src/changelist/_cli.py | 7 +++----
 1 file changed, 3 insertions(+), 4 deletions(-)

diff --git a/src/changelist/_cli.py b/src/changelist/_cli.py
index bdafcde..9abf6b2 100644
--- a/src/changelist/_cli.py
+++ b/src/changelist/_cli.py
@@ -152,6 +152,7 @@ def main(
         pull_requests=lazy_tqdm(pull_requests, desc="Fetching reviewers"),
     )
 
+    print("Formatting notes...", file=sys.stderr)
     change_notes = ChangeNote.from_pull_requests(
         pull_requests,
         pr_summary_regex=re.compile(config["pr_summary_regex"], flags=re.MULTILINE),
@@ -178,7 +179,5 @@ def main(
             io.writelines(formatter.iter_lines())
     else:
         print()
-        for line in formatter.iter_lines():
-            assert line.endswith("\n")
-            assert line.count("\n") == 1
-            print(line, end="", file=sys.stdout)
+        notes = str(formatter)
+        print(notes, file=sys.stdout)

From 831a0e13f40980160108b9338b5975387120efb3 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Lars=20Gr=C3=BCter?= <lagru@mailbox.org>
Date: Mon, 13 Nov 2023 20:03:58 +0100
Subject: [PATCH 04/16] Add basic integration tests for the formatter classes

This is nothing to fancy but it should catch unexpected changes in
our formatting logic and cover the happy path.
---
 pyproject.toml            |   6 +++
 src/changelist/_format.py |   4 +-
 test/desired_notes.md     |  37 ++++++++++++++
 test/desired_notes.rst    |  44 ++++++++++++++++
 test/test_format.py       | 105 ++++++++++++++++++++++++++++++++++++++
 5 files changed, 194 insertions(+), 2 deletions(-)
 create mode 100644 test/desired_notes.md
 create mode 100644 test/desired_notes.rst
 create mode 100644 test/test_format.py

diff --git a/pyproject.toml b/pyproject.toml
index 3625f6c..5fa9aa5 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -33,6 +33,7 @@ changelist = "changelist.__main__:main"
 
 [project.optional-dependencies]
 lint = ["pre-commit == 3.5.0"]
+test = ["pytest", "pytest-cov"]
 
 [tool.ruff]
 line-length = 88
@@ -46,3 +47,8 @@ select = [
     "I",
     "UP",
 ]
+
+[tool.pytest.ini_options]
+minversion = "6.0"
+addopts = "--doctest-modules"
+testpaths = ["src", "test"]
diff --git a/src/changelist/_format.py b/src/changelist/_format.py
index ea6a6d2..034d19a 100644
--- a/src/changelist/_format.py
+++ b/src/changelist/_format.py
@@ -240,14 +240,14 @@ def _format_intro(self):
             repo_name=self.repo_name, version=self.version
         )
         # Make sure to return exactly one line at a time
-        yield from (f"{line}\n" for line in intro.split("\n"))
+        yield from (f"{self._sanitize_text(line)}\n" for line in intro.split("\n"))
 
     def _format_outro(self) -> Iterable[str]:
         outro = self.outro_template.format(
             repo_name=self.repo_name, version=self.version
         )
         # Make sure to return exactly one line at a time
-        yield from (f"{line}\n" for line in outro.split("\n"))
+        yield from (f"{self._sanitize_text(line)}\n" for line in outro.split("\n"))
 
 
 class RstFormatter(MdFormatter):
diff --git a/test/desired_notes.md b/test/desired_notes.md
new file mode 100644
index 0000000..fb7f554
--- /dev/null
+++ b/test/desired_notes.md
@@ -0,0 +1,37 @@
+# foolib 1.0
+
+Intro with `literal` for foolib 1.0!
+
+## New Features
+
+- Add `foo` ([#1](https://github.com/foo-group/foolib/pull/1)).
+
+## API Changes
+
+- Deprecate `bar` ([#1](https://github.com/foo-group/foolib/pull/1)).
+
+## Bug Fixes
+
+- Deprecate `bar` ([#1](https://github.com/foo-group/foolib/pull/1)).
+
+## Documentation
+
+- Create tutorial about newlines ([#2](https://github.com/foo-group/foolib/pull/2)).
+
+## Other
+
+- Unlabeled change. With multiple sentences ([#2](https://github.com/foo-group/foolib/pull/3)).
+
+## Contributors
+
+2 authors added to this release (alphabetically):
+
+- [@madhu-esen](https://github.com/madhu-esen)
+- Nur Lungile ([@lungile](https://github.com/lungile))
+
+2 reviewers added to this release (alphabetically):
+
+- [@madhu-esen](https://github.com/madhu-esen)
+- Nur Lungile ([@lungile](https://github.com/lungile))
+
+Outro with `literal`.
diff --git a/test/desired_notes.rst b/test/desired_notes.rst
new file mode 100644
index 0000000..8251d87
--- /dev/null
+++ b/test/desired_notes.rst
@@ -0,0 +1,44 @@
+foolib 1.0
+==========
+
+Intro with ``literal`` for foolib 1.0!
+
+New Features
+------------
+
+- Add ``foo`` (`#1 <https://github.com/foo-group/foolib/pull/1>`_).
+
+API Changes
+-----------
+
+- Deprecate ``bar`` (`#1 <https://github.com/foo-group/foolib/pull/1>`_).
+
+Bug Fixes
+---------
+
+- Deprecate ``bar`` (`#1 <https://github.com/foo-group/foolib/pull/1>`_).
+
+Documentation
+-------------
+
+- Create tutorial about newlines (`#2 <https://github.com/foo-group/foolib/pull/2>`_).
+
+Other
+-----
+
+- Unlabeled change. With multiple sentences (`#2 <https://github.com/foo-group/foolib/pull/3>`_).
+
+Contributors
+------------
+
+2 authors added to this release (alphabetically):
+
+- `@madhu-esen <https://github.com/madhu-esen>`_
+- Nur Lungile (`@lungile <https://github.com/lungile>`_)
+
+2 reviewers added to this release (alphabetically):
+
+- `@madhu-esen <https://github.com/madhu-esen>`_
+- Nur Lungile (`@lungile <https://github.com/lungile>`_)
+
+Outro with ``literal``.
diff --git a/test/test_format.py b/test/test_format.py
new file mode 100644
index 0000000..92f7ee7
--- /dev/null
+++ b/test/test_format.py
@@ -0,0 +1,105 @@
+from datetime import datetime
+from pathlib import Path
+
+from changelist._format import ChangeNote, Contributor, MdFormatter, RstFormatter
+
+here = Path(__file__).parent
+
+NOTES = (
+    ChangeNote(
+        content="Add `foo`.",
+        reference_name="#1",
+        reference_url="https://github.com/foo-group/foolib/pull/1",
+        labels=("New feature",),
+        timestamp=datetime(2023, 1, 1),
+    ),
+    ChangeNote(
+        content="Deprecate `bar`",
+        reference_name="#1",
+        reference_url="https://github.com/foo-group/foolib/pull/1",
+        labels=("api", "Bug fix"),
+        timestamp=datetime(2023, 1, 1),
+    ),
+    ChangeNote(
+        content="Create tutorial\nabout newlines.",
+        reference_name="#2",
+        reference_url="https://github.com/foo-group/foolib/pull/2",
+        labels=("documentation",),
+        timestamp=datetime(2023, 1, 2),
+    ),
+    ChangeNote(
+        content="Unlabeled change. With\nmultiple sentences.",
+        reference_name="#2",
+        reference_url="https://github.com/foo-group/foolib/pull/3",
+        labels=(),
+        timestamp=datetime(2023, 1, 3),
+    ),
+)
+
+CONTRIBUTORS = (
+    Contributor(
+        name="Nur Lungile",
+        login="lungile",
+        reference_url="https://github.com/lungile",
+    ),
+    Contributor(
+        name=None,
+        login="madhu-esen",
+        reference_url="https://github.com/madhu-esen",
+    ),
+    Contributor(
+        name="bot",
+        login="bot",
+        reference_url="https://github.com/apps/bot",
+    ),
+)
+
+LABEL_SECTION_MAP = {
+    ".*New feature.*": "New Features",
+    ".*API.*": "API Changes",
+    ".*Bug fix.*": "Bug Fixes",
+    ".*Documentation.*": "Documentation",
+}
+
+DEFAULT_FORMATTER_KWARGS = {
+    "repo_name": "foolib",
+    "change_notes": set(NOTES),
+    "authors": set(CONTRIBUTORS),
+    "reviewers": set(CONTRIBUTORS),
+    "version": "1.0",
+    "title_template": "{repo_name} {version}",
+    "intro_template": "Intro with `literal` for {repo_name} {version}!\n",
+    "outro_template": "Outro with `literal`.",
+    "label_section_map": LABEL_SECTION_MAP,
+    "ignored_user_logins": ("bot"),
+}
+
+
+class Test_MdFormatter:
+    def test_iteration(self):
+        formatter = MdFormatter(**DEFAULT_FORMATTER_KWARGS)
+        for line in formatter:
+            assert line.endswith("\n")
+            assert line.count("\n") == 1
+
+    def test_full(self):
+        formatter = MdFormatter(**DEFAULT_FORMATTER_KWARGS)
+        result = str(formatter)
+        with (here / "desired_notes.md").open() as file:
+            desired = file.read()
+        assert result == desired
+
+
+class Test_RstFormatter:
+    def test_iteration(self):
+        formatter = RstFormatter(**DEFAULT_FORMATTER_KWARGS)
+        for line in formatter:
+            assert line.endswith("\n")
+            assert line.count("\n") == 1
+
+    def test_full(self):
+        formatter = RstFormatter(**DEFAULT_FORMATTER_KWARGS)
+        result = str(formatter)
+        with (here / "desired_notes.rst").open() as file:
+            desired = file.read()
+        assert result == desired

From 219c92d8ca567126fd4e544d6ad17ab2ef7f8071 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Lars=20Gr=C3=BCter?= <lagru@mailbox.org>
Date: Mon, 13 Nov 2023 20:12:22 +0100
Subject: [PATCH 05/16] Add CI workflow for test suite

---
 .github/workflows/test.yml | 33 +++++++++++++++++++++++++++++++++
 1 file changed, 33 insertions(+)
 create mode 100644 .github/workflows/test.yml

diff --git a/.github/workflows/test.yml b/.github/workflows/test.yml
new file mode 100644
index 0000000..1ed2539
--- /dev/null
+++ b/.github/workflows/test.yml
@@ -0,0 +1,33 @@
+name: test
+
+on: [push, pull_request]
+
+jobs:
+  pytest:
+    runs-on: ${{ matrix.os }}-latest
+    strategy:
+      matrix:
+        os: [ubuntu]
+        python-version: ["3.9", "3.10", "3.11"]
+
+    steps:
+      - uses: actions/checkout@v4
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v4
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - uses: actions/cache@v3
+        with:
+          path: ~/.cache/pip
+          key: ${{ runner.os }}-pip-${{ hashFiles('**/pyproject.toml') }}
+          restore-keys: |
+            ${{ runner.os }}-pip-
+
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install .[test]
+
+      - name: Test
+        run: pytest --cov

From 62cbdac99119ba37cd3c16df524485d131163dd1 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Lars=20Gr=C3=BCter?= <lagru@mailbox.org>
Date: Tue, 14 Nov 2023 01:06:10 +0100
Subject: [PATCH 06/16] Postpone Python 3.10 dataclass features

---
 pyproject.toml            | 1 +
 src/changelist/_format.py | 8 ++++----
 src/changelist/_query.py  | 2 +-
 3 files changed, 6 insertions(+), 5 deletions(-)

diff --git a/pyproject.toml b/pyproject.toml
index 5fa9aa5..b87599f 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -5,6 +5,7 @@ build-backend = "setuptools.build_meta"
 [project]
 name = "changelist"
 version = "0.5rc0.dev0"
+# TODO add slots=True, kw_only=True to dataclasses starting with >=3.10
 requires-python = ">=3.9"
 readme = "README.md"
 license = {file = "LICENSE.txt"}
diff --git a/src/changelist/_format.py b/src/changelist/_format.py
index 034d19a..91eb794 100644
--- a/src/changelist/_format.py
+++ b/src/changelist/_format.py
@@ -11,7 +11,7 @@
 logger = logging.getLogger(__name__)
 
 
-@dataclass(frozen=True, slots=True, kw_only=True)
+@dataclass(frozen=True)
 class ChangeNote:
     """Describes an atomic change in the notes."""
 
@@ -65,7 +65,7 @@ def from_pull_requests(
         return notes
 
 
-@dataclass(frozen=True, slots=True, kw_only=True)
+@dataclass(frozen=True)
 class Contributor:
     """A person mentioned in the notes as an author or reviewer.
 
@@ -74,7 +74,7 @@ class Contributor:
      contributor's GitHub profile.
     """
 
-    name: str | None
+    name: str
     login: str
     reference_url: str
 
@@ -98,7 +98,7 @@ def from_named_users(cls, named_users: set[NamedUser]) -> "set[Contributor]":
         return contributors
 
 
-@dataclass(frozen=True, kw_only=True)
+@dataclass(frozen=True)
 class MdFormatter:
     """Format release notes in Markdown from PRs, authors and reviewers."""
 
diff --git a/src/changelist/_query.py b/src/changelist/_query.py
index 5be4228..25aad81 100644
--- a/src/changelist/_query.py
+++ b/src/changelist/_query.py
@@ -51,7 +51,7 @@ def pull_requests_from_commits(commits: Iterable[Commit]) -> set[PullRequest]:
     return all_pull_requests
 
 
-@dataclass(frozen=True, kw_only=True)
+@dataclass(frozen=True)
 class GitHubGraphQl:
     """Interface to query GitHub's GraphQL API for a particular repository."""
 

From b56b06389d2a3bf4e42e7e678258e4329e52da47 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Lars=20Gr=C3=BCter?= <lagru+github@mailbox.org>
Date: Wed, 29 Nov 2023 09:06:57 +0100
Subject: [PATCH 07/16] Remove whitespace

Co-authored-by: Stefan van der Walt <sjvdwalt@gmail.com>
---
 src/changelist/_format.py | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/src/changelist/_format.py b/src/changelist/_format.py
index 91eb794..e9939e9 100644
--- a/src/changelist/_format.py
+++ b/src/changelist/_format.py
@@ -33,7 +33,7 @@ def from_pull_requests(
         Create one or more notes describing an atomic change from each given
         pull request.
 
-        `pr_summary_regex` is used to detect one or multiple  notes in a pull
+        `pr_summary_regex` is used to detect one or multiple notes in a pull
         request description that will be used instead of the pull request title
         if present. This uncouples pull requests and notes somewhat. While
         ideally, a pull request introduces a change that would be described in

From 6c7c41bc263795309d0d78797405b67ab9df8a54 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Lars=20Gr=C3=BCter?= <lagru+github@mailbox.org>
Date: Wed, 29 Nov 2023 09:07:25 +0100
Subject: [PATCH 08/16] Remove whitespace

Co-authored-by: Stefan van der Walt <sjvdwalt@gmail.com>
---
 src/changelist/_format.py | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/src/changelist/_format.py b/src/changelist/_format.py
index e9939e9..28b25a4 100644
--- a/src/changelist/_format.py
+++ b/src/changelist/_format.py
@@ -69,7 +69,7 @@ def from_pull_requests(
 class Contributor:
     """A person mentioned in the notes as an author or reviewer.
 
-    `login` should be the GitHub  handle without "@". The "@" is added by the
+    `login` should be the GitHub handle without "@". The "@" is added by the
     `reference_name` property. `reference_url` is typically a URL to the
      contributor's GitHub profile.
     """

From f5aac7e32471eebbb526e213139d3d8526019178 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Lars=20Gr=C3=BCter?= <lagru@mailbox.org>
Date: Tue, 9 Jan 2024 15:09:34 +0100
Subject: [PATCH 09/16] Use fenced-code block based syntax for summary labels

This syntax should hopefully be more robust than the previous one based
on the relatively common ":" character.
---
 README.md                          |  34 +++++---
 src/changelist/_cli.py             |   7 +-
 src/changelist/_format.py          |  91 +---------------------
 src/changelist/_objects.py         | 120 +++++++++++++++++++++++++++++
 src/changelist/default_config.toml |  34 +++++---
 test/test_format.py                |  20 ++---
 test/test_objects.py               |  69 +++++++++++++++++
 7 files changed, 252 insertions(+), 123 deletions(-)
 create mode 100644 src/changelist/_objects.py
 create mode 100644 test/test_objects.py

diff --git a/README.md b/README.md
index 38b401a..7dfdfbe 100644
--- a/README.md
+++ b/README.md
@@ -83,21 +83,37 @@ ignored_user_logins = [
 ]
 
 # If this regex matches a pull requests description, the captured content
-# is included instead of the pull request title. The regex is allowed to match
-# more than once in which case a single pull request may result in multiple
-# items. Each summary can optionally be prefixed with a `Label:` which takes
-# precedence over the pull requests labels. This is useful if one pull request
-# should be summarized in different sections.
-# E.g. the default regex below is matched by
+# is included instead of the pull request title. E.g. the
+# default regex below is matched by
 #
 # ```release-note
-# Label: An ideally expressive description of the change that is included as
+# An ideally expressive description of the change that is included as
 # a single bullet point. Newlines are removed.
 # ```
 #
 # If you modify this regex, make sure to match the content with a capture
-# group named "summary".
-pr_summary_regex = "^```release-note\\s*((?P<label>[^:]*):)?(?P<summary>[\\s\\S]*?\\w[\\s\\S]*?)\\s*^```"
+# group named "summary". The regex is allowed to match more than once in which
+# case a single pull request may result in multiple items (see
+# `pr_summary_label_regex` for why that might be useful).
+pr_summary_regex = "^```release-note\\s*(?P<summary>[\\s\\S]*?\\w[\\s\\S]*?)\\s*^```"
+
+# Sometimes pull requests introduce changes that should be listed in different
+# sections. For that reason, `pr_summary_regex` can match more than once and
+# this regex, `pr_summary_label_regex`, can be used to add independent labels
+# to each summary. E.g. the example below will both match and go into separate
+# sections
+#
+# ```release-note {label="Bug fix"}
+# Make `is_odd()` work for negative numbers.
+# ```
+#
+# ```release-note
+# Deprecate `ìs_odd`; use `not (x % 2)` instead! {label="API, Highlight"}
+# ```
+#
+# If you modify this regex, make sure to match the content with a capture
+# group named "label".
+pr_summary_label_regex = """{label=[\\"'](?P<label>[^}]+)[\\"']}"""
 
 # If any of a pull request's labels matches one of the regexes on the left side
 # its summary will appear in the appropriate section with the title given on
diff --git a/src/changelist/_cli.py b/src/changelist/_cli.py
index 9abf6b2..46c0bdb 100644
--- a/src/changelist/_cli.py
+++ b/src/changelist/_cli.py
@@ -1,7 +1,6 @@
 import argparse
 import logging
 import os
-import re
 import sys
 import tempfile
 from pathlib import Path
@@ -12,7 +11,8 @@
 from tqdm import tqdm
 
 from ._config import add_config_defaults, local_config, remote_config
-from ._format import ChangeNote, Contributor, MdFormatter, RstFormatter
+from ._format import MdFormatter, RstFormatter
+from ._objects import ChangeNote, Contributor
 from ._query import commits_between, contributors, pull_requests_from_commits
 
 logger = logging.getLogger(__name__)
@@ -155,7 +155,8 @@ def main(
     print("Formatting notes...", file=sys.stderr)
     change_notes = ChangeNote.from_pull_requests(
         pull_requests,
-        pr_summary_regex=re.compile(config["pr_summary_regex"], flags=re.MULTILINE),
+        pr_summary_regex=config["pr_summary_regex"],
+        pr_summary_label_regex=config["pr_summary_label_regex"],
     )
 
     Formatter = {"md": MdFormatter, "rst": RstFormatter}[format]
diff --git a/src/changelist/_format.py b/src/changelist/_format.py
index 28b25a4..2a99681 100644
--- a/src/changelist/_format.py
+++ b/src/changelist/_format.py
@@ -3,101 +3,12 @@
 from collections import OrderedDict
 from collections.abc import Iterable
 from dataclasses import dataclass
-from datetime import datetime
 
-from github.NamedUser import NamedUser
-from github.PullRequest import PullRequest
+from changelist._objects import ChangeNote, Contributor
 
 logger = logging.getLogger(__name__)
 
 
-@dataclass(frozen=True)
-class ChangeNote:
-    """Describes an atomic change in the notes."""
-
-    content: str
-    reference_name: str
-    reference_url: str
-    labels: tuple[str, ...]
-    timestamp: datetime
-
-    @classmethod
-    def from_pull_requests(
-        cls,
-        pull_requests: set[PullRequest],
-        *,
-        pr_summary_regex: re.Pattern,
-    ) -> "set[ChangeNote]":
-        """Create a set of notes from pull requests.
-
-        Create one or more notes describing an atomic change from each given
-        pull request.
-
-        `pr_summary_regex` is used to detect one or multiple notes in a pull
-        request description that will be used instead of the pull request title
-        if present. This uncouples pull requests and notes somewhat. While
-        ideally, a pull request introduces a change that would be described in
-        a single note, this is often not the case.
-        """
-        notes = set()
-        for pr in pull_requests:
-            if not pr.body or not (
-                matches := tuple(pr_summary_regex.finditer(pr.body))
-            ):
-                logger.debug("falling back to title for %s", pr.html_url)
-                matches = ({"summary": pr.title, "label": None},)
-            assert len(matches) >= 1
-            for match in matches:
-                summary = match["summary"]
-                if match["label"] is not None:
-                    labels = (match["label"],)
-                else:
-                    labels = tuple(label.name for label in pr.labels)
-                notes.add(
-                    cls(
-                        content=summary.strip(),
-                        reference_name=f"#{pr.number}",
-                        reference_url=pr.html_url,
-                        labels=labels,
-                        timestamp=pr.merged_at,
-                    )
-                )
-        return notes
-
-
-@dataclass(frozen=True)
-class Contributor:
-    """A person mentioned in the notes as an author or reviewer.
-
-    `login` should be the GitHub handle without "@". The "@" is added by the
-    `reference_name` property. `reference_url` is typically a URL to the
-     contributor's GitHub profile.
-    """
-
-    name: str
-    login: str
-    reference_url: str
-
-    @property
-    def reference_name(self) -> str:
-        """The GitHub login handle with prefixed "@"."""
-        return f"@{self.login}"
-
-    @classmethod
-    def from_named_users(cls, named_users: set[NamedUser]) -> "set[Contributor]":
-        """ """
-        contributors = set()
-        for user in named_users:
-            contributors.add(
-                cls(
-                    name=user.name,
-                    login=user.login,
-                    reference_url=user.html_url,
-                )
-            )
-        return contributors
-
-
 @dataclass(frozen=True)
 class MdFormatter:
     """Format release notes in Markdown from PRs, authors and reviewers."""
diff --git a/src/changelist/_objects.py b/src/changelist/_objects.py
new file mode 100644
index 0000000..8a791c0
--- /dev/null
+++ b/src/changelist/_objects.py
@@ -0,0 +1,120 @@
+import logging
+import re
+from dataclasses import dataclass
+from datetime import datetime
+
+from github.NamedUser import NamedUser
+from github.PullRequest import PullRequest
+
+logger = logging.getLogger(__name__)
+
+
+@dataclass(frozen=True)
+class ChangeNote:
+    """Describes an atomic change in the notes."""
+
+    content: str
+    reference_name: str
+    reference_url: str
+    labels: tuple[str, ...]
+    timestamp: datetime
+
+    @classmethod
+    def from_pull_requests(
+        cls,
+        pull_requests: set[PullRequest],
+        *,
+        pr_summary_regex: str,
+        pr_summary_label_regex: str,
+    ) -> "set[ChangeNote]":
+        """Create a set of notes from pull requests.
+
+        Create one or more notes describing an atomic change from each given
+        pull request.
+
+        `pr_summary_regex` and `pr_summary_label_regex` are used to detect one
+        or multiple notes in a pull request description that will be used
+        instead of the pull request title if present. This uncouples pull
+        requests and notes somewhat. While ideally, a pull request introduces
+        a change that would be described in a single note, this is often not
+        the case.
+        """
+        pr_summary_regex = re.compile(pr_summary_regex, flags=re.MULTILINE)
+        pr_summary_label_regex = re.compile(pr_summary_label_regex)
+
+        notes = set()
+        for pr in pull_requests:
+            pr_labels = tuple(label.name for label in pr.labels)
+
+            if not pr.body or not (
+                matches := tuple(pr_summary_regex.finditer(pr.body))
+            ):
+                logger.debug("falling back to title for %s", pr.html_url)
+                notes.add(
+                    cls(
+                        content=pr.title.strip(),
+                        reference_name=f"#{pr.number}",
+                        reference_url=pr.html_url,
+                        labels=pr_labels,
+                        timestamp=pr.merged_at,
+                    )
+                )
+                continue
+
+            assert len(matches) >= 1
+            for match in matches:
+                summary = match["summary"]
+                label_match = pr_summary_label_regex.search(summary)
+                if label_match:
+                    labels = tuple(
+                        label.strip() for label in label_match["label"].split(",")
+                    )
+                    summary = pr_summary_label_regex.sub("", summary)
+                else:
+                    logger.debug(
+                        "falling back to PR labels for summary in %s", pr.html_url
+                    )
+                    labels = pr_labels
+                notes.add(
+                    cls(
+                        content=summary.strip(),
+                        reference_name=f"#{pr.number}",
+                        reference_url=pr.html_url,
+                        labels=labels,
+                        timestamp=pr.merged_at,
+                    )
+                )
+        return notes
+
+
+@dataclass(frozen=True)
+class Contributor:
+    """A person mentioned in the notes as an author or reviewer.
+
+    `login` should be the GitHub handle without "@". The "@" is added by the
+    `reference_name` property. `reference_url` is typically a URL to the
+     contributor's GitHub profile.
+    """
+
+    name: str | None
+    login: str
+    reference_url: str
+
+    @property
+    def reference_name(self) -> str:
+        """The GitHub login handle with prefixed "@"."""
+        return f"@{self.login}"
+
+    @classmethod
+    def from_named_users(cls, named_users: set[NamedUser]) -> "set[Contributor]":
+        """ """
+        contributors = set()
+        for user in named_users:
+            contributors.add(
+                cls(
+                    name=user.name,
+                    login=user.login,
+                    reference_url=user.html_url,
+                )
+            )
+        return contributors
diff --git a/src/changelist/default_config.toml b/src/changelist/default_config.toml
index 2083549..cac107d 100644
--- a/src/changelist/default_config.toml
+++ b/src/changelist/default_config.toml
@@ -27,21 +27,37 @@ ignored_user_logins = [
 ]
 
 # If this regex matches a pull requests description, the captured content
-# is included instead of the pull request title. The regex is allowed to match
-# more than once in which case a single pull request may result in multiple
-# items. Each summary can optionally be prefixed with a `Label:` which takes
-# precedence over the pull requests labels. This is useful if one pull request
-# should be summarized in different sections.
-# E.g. the default regex below is matched by
+# is included instead of the pull request title. E.g. the
+# default regex below is matched by
 #
 # ```release-note
-# Label: An ideally expressive description of the change that is included as
+# An ideally expressive description of the change that is included as
 # a single bullet point. Newlines are removed.
 # ```
 #
 # If you modify this regex, make sure to match the content with a capture
-# group named "summary".
-pr_summary_regex = "^```release-note\\s*((?P<label>[^:]*):)?(?P<summary>[\\s\\S]*?\\w[\\s\\S]*?)\\s*^```"
+# group named "summary". The regex is allowed to match more than once in which
+# case a single pull request may result in multiple items (see
+# `pr_summary_label_regex` for why that might be useful).
+pr_summary_regex = "^```release-note\\s*(?P<summary>[\\s\\S]*?\\w[\\s\\S]*?)\\s*^```"
+
+# Sometimes pull requests introduce changes that should be listed in different
+# sections. For that reason, `pr_summary_regex` can match more than once and
+# this regex, `pr_summary_label_regex`, can be used to add independent labels
+# to each summary. E.g. the example below will both match and go into separate
+# sections
+#
+# ```release-note {label="Bug fix"}
+# Make `is_odd()` work for negative numbers.
+# ```
+#
+# ```release-note
+# Deprecate `ìs_odd`; use `not (x % 2)` instead! {label="API, Highlight"}
+# ```
+#
+# If you modify this regex, make sure to match the content with a capture
+# group named "label".
+pr_summary_label_regex = """{label=[\\"'](?P<label>[^}]+)[\\"']}"""
 
 # If any of a pull request's labels matches one of the regexes on the left side
 # its summary will appear in the appropriate section with the title given on
diff --git a/test/test_format.py b/test/test_format.py
index 92f7ee7..99135d2 100644
--- a/test/test_format.py
+++ b/test/test_format.py
@@ -1,10 +1,13 @@
 from datetime import datetime
 from pathlib import Path
 
+from changelist._config import DEFAULT_CONFIG_PATH, local_config
 from changelist._format import ChangeNote, Contributor, MdFormatter, RstFormatter
 
 here = Path(__file__).parent
 
+DEFAULT_CONFIG = local_config(DEFAULT_CONFIG_PATH)
+
 NOTES = (
     ChangeNote(
         content="Add `foo`.",
@@ -48,30 +51,23 @@
         reference_url="https://github.com/madhu-esen",
     ),
     Contributor(
-        name="bot",
-        login="bot",
+        name=None,
+        login="web-flow",
         reference_url="https://github.com/apps/bot",
     ),
 )
 
-LABEL_SECTION_MAP = {
-    ".*New feature.*": "New Features",
-    ".*API.*": "API Changes",
-    ".*Bug fix.*": "Bug Fixes",
-    ".*Documentation.*": "Documentation",
-}
-
 DEFAULT_FORMATTER_KWARGS = {
     "repo_name": "foolib",
     "change_notes": set(NOTES),
     "authors": set(CONTRIBUTORS),
     "reviewers": set(CONTRIBUTORS),
     "version": "1.0",
-    "title_template": "{repo_name} {version}",
+    "title_template": DEFAULT_CONFIG["title_template"],
     "intro_template": "Intro with `literal` for {repo_name} {version}!\n",
     "outro_template": "Outro with `literal`.",
-    "label_section_map": LABEL_SECTION_MAP,
-    "ignored_user_logins": ("bot"),
+    "label_section_map": DEFAULT_CONFIG["label_section_map"],
+    "ignored_user_logins": DEFAULT_CONFIG["ignored_user_logins"],
 }
 
 
diff --git a/test/test_objects.py b/test/test_objects.py
new file mode 100644
index 0000000..11fce80
--- /dev/null
+++ b/test/test_objects.py
@@ -0,0 +1,69 @@
+from dataclasses import dataclass
+from datetime import datetime
+from pathlib import Path
+
+from changelist._config import DEFAULT_CONFIG_PATH, local_config
+from changelist._objects import ChangeNote
+
+here = Path(__file__).parent
+
+
+DEFAULT_CONFIG = local_config(DEFAULT_CONFIG_PATH)
+
+
+@dataclass
+class _MockLabel:
+    name: str
+
+
+@dataclass
+class _MockPullRequest:
+    title: str
+    body: str | None
+    labels: list[_MockLabel]
+    number: int = (42,)
+    html_url: str = "https://github.com/scientific-python/changelist/pull/53"
+    merged_at: datetime = datetime(2024, 1, 1)
+
+
+class Test_ChangeNote:
+    def test_from_pull_requests(self, caplog):
+        caplog.set_level("DEBUG")
+        body = """
+Some ignored text in the pull request body.
+
+```release-note
+Deprecate `ìs_odd`; use `not (x % 2)` instead! {label="API, Highlight"}
+```
+```release-note
+Document how to test for oddness of a number.
+```
+
+```release-note {label="Bug fix"}
+Make `is_odd()` work for negative numbers.
+```
+"""
+        pull_request = _MockPullRequest(
+            title="The title",
+            body=body,
+            labels=[_MockLabel("Documentation")],
+        )
+        notes = ChangeNote.from_pull_requests(
+            [pull_request],
+            pr_summary_regex=DEFAULT_CONFIG["pr_summary_regex"],
+            pr_summary_label_regex=DEFAULT_CONFIG["pr_summary_label_regex"],
+        )
+        assert len(notes) == 3
+        notes = sorted(notes, key=lambda n: n.content)
+        assert notes[0].content == "Deprecate `ìs_odd`; use `not (x % 2)` instead!"
+        assert notes[0].labels == ("API", "Highlight")
+
+        assert notes[1].content == "Document how to test for oddness of a number."
+        assert notes[1].labels == ("Documentation",)
+
+        assert notes[2].content == "Make `is_odd()` work for negative numbers."
+        assert notes[2].labels == ("Bug fix",)
+
+        assert len(caplog.records) == 1
+        assert caplog.records[0].levelname == "DEBUG"
+        assert "falling back to PR labels for summary" in caplog.records[0].msg

From c8258f8b591295a52754543917347eeba1687124 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Lars=20Gr=C3=BCter?= <lagru@mailbox.org>
Date: Tue, 9 Jan 2024 15:14:11 +0100
Subject: [PATCH 10/16] Document that summary and PR labels correspond

---
 README.md                          | 5 +++--
 src/changelist/default_config.toml | 5 +++--
 2 files changed, 6 insertions(+), 4 deletions(-)

diff --git a/README.md b/README.md
index 7dfdfbe..389ab36 100644
--- a/README.md
+++ b/README.md
@@ -100,8 +100,9 @@ pr_summary_regex = "^```release-note\\s*(?P<summary>[\\s\\S]*?\\w[\\s\\S]*?)\\s*
 # Sometimes pull requests introduce changes that should be listed in different
 # sections. For that reason, `pr_summary_regex` can match more than once and
 # this regex, `pr_summary_label_regex`, can be used to add independent labels
-# to each summary. E.g. the example below will both match and go into separate
-# sections
+# to each summary. These labels are sorted with the `label_section_map` the
+# same way as regular pull request labels are. E.g. the example below will both
+# match and go into separate sections:
 #
 # ```release-note {label="Bug fix"}
 # Make `is_odd()` work for negative numbers.
diff --git a/src/changelist/default_config.toml b/src/changelist/default_config.toml
index cac107d..46dbcf7 100644
--- a/src/changelist/default_config.toml
+++ b/src/changelist/default_config.toml
@@ -44,8 +44,9 @@ pr_summary_regex = "^```release-note\\s*(?P<summary>[\\s\\S]*?\\w[\\s\\S]*?)\\s*
 # Sometimes pull requests introduce changes that should be listed in different
 # sections. For that reason, `pr_summary_regex` can match more than once and
 # this regex, `pr_summary_label_regex`, can be used to add independent labels
-# to each summary. E.g. the example below will both match and go into separate
-# sections
+# to each summary. These labels are sorted with the `label_section_map` the
+# same way as regular pull request labels are. E.g. the example below will both
+# match and go into separate sections:
 #
 # ```release-note {label="Bug fix"}
 # Make `is_odd()` work for negative numbers.

From 3db572520dd4a06f1df745a2612e77684df80abf Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Lars=20Gr=C3=BCter?= <lagru@mailbox.org>
Date: Tue, 9 Jan 2024 17:06:27 +0100
Subject: [PATCH 11/16] Use Py3.9 compatible typing

---
 src/changelist/_objects.py | 3 ++-
 test/test_objects.py       | 3 ++-
 2 files changed, 4 insertions(+), 2 deletions(-)

diff --git a/src/changelist/_objects.py b/src/changelist/_objects.py
index 8a791c0..1d20f78 100644
--- a/src/changelist/_objects.py
+++ b/src/changelist/_objects.py
@@ -2,6 +2,7 @@
 import re
 from dataclasses import dataclass
 from datetime import datetime
+from typing import Union
 
 from github.NamedUser import NamedUser
 from github.PullRequest import PullRequest
@@ -96,7 +97,7 @@ class Contributor:
      contributor's GitHub profile.
     """
 
-    name: str | None
+    name: Union[str, None]
     login: str
     reference_url: str
 
diff --git a/test/test_objects.py b/test/test_objects.py
index 11fce80..675cfbf 100644
--- a/test/test_objects.py
+++ b/test/test_objects.py
@@ -1,6 +1,7 @@
 from dataclasses import dataclass
 from datetime import datetime
 from pathlib import Path
+from typing import Union
 
 from changelist._config import DEFAULT_CONFIG_PATH, local_config
 from changelist._objects import ChangeNote
@@ -19,7 +20,7 @@ class _MockLabel:
 @dataclass
 class _MockPullRequest:
     title: str
-    body: str | None
+    body: Union[str, None]
     labels: list[_MockLabel]
     number: int = (42,)
     html_url: str = "https://github.com/scientific-python/changelist/pull/53"

From e99aa5f541754a7053eb5afe58ca73e86e7072ab Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Lars=20Gr=C3=BCter?= <lagru@mailbox.org>
Date: Tue, 9 Jan 2024 17:07:14 +0100
Subject: [PATCH 12/16] Account for unrelated attributes in fenced code block

---
 README.md                          | 2 +-
 src/changelist/default_config.toml | 2 +-
 test/test_objects.py               | 2 +-
 3 files changed, 3 insertions(+), 3 deletions(-)

diff --git a/README.md b/README.md
index 808ac6b..21b8696 100644
--- a/README.md
+++ b/README.md
@@ -110,7 +110,7 @@ pr_summary_regex = "^```release-note\\s*(?P<summary>[\\s\\S]*?\\w[\\s\\S]*?)\\s*
 #
 # If you modify this regex, make sure to match the content with a capture
 # group named "label".
-pr_summary_label_regex = """{label=[\\"'](?P<label>[^}]+)[\\"']}"""
+pr_summary_label_regex = """{[^}]*?label=[\\"](?P<label>[^\\"]+)[^}]*?}"""
 
 # If any of a pull request's labels matches one of the regexes on the left side
 # its summary will appear in the appropriate section with the title given on
diff --git a/src/changelist/default_config.toml b/src/changelist/default_config.toml
index 46dbcf7..67e0a77 100644
--- a/src/changelist/default_config.toml
+++ b/src/changelist/default_config.toml
@@ -58,7 +58,7 @@ pr_summary_regex = "^```release-note\\s*(?P<summary>[\\s\\S]*?\\w[\\s\\S]*?)\\s*
 #
 # If you modify this regex, make sure to match the content with a capture
 # group named "label".
-pr_summary_label_regex = """{label=[\\"'](?P<label>[^}]+)[\\"']}"""
+pr_summary_label_regex = """{[^}]*?label=[\\"](?P<label>[^\\"]+)[^}]*?}"""
 
 # If any of a pull request's labels matches one of the regexes on the left side
 # its summary will appear in the appropriate section with the title given on
diff --git a/test/test_objects.py b/test/test_objects.py
index 675cfbf..96c44c1 100644
--- a/test/test_objects.py
+++ b/test/test_objects.py
@@ -40,7 +40,7 @@ def test_from_pull_requests(self, caplog):
 Document how to test for oddness of a number.
 ```
 
-```release-note {label="Bug fix"}
+```release-note {.someClass label="Bug fix" otherAttribute="test"}
 Make `is_odd()` work for negative numbers.
 ```
 """

From d22a760080f211b9448a9dbb3a2038be55f3930c Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Lars=20Gr=C3=BCter?= <lagru@mailbox.org>
Date: Tue, 9 Jan 2024 17:13:19 +0100
Subject: [PATCH 13/16] Test for fallback to title

---
 test/test_objects.py | 23 ++++++++++++++++++++++-
 1 file changed, 22 insertions(+), 1 deletion(-)

diff --git a/test/test_objects.py b/test/test_objects.py
index 96c44c1..3f6c9cf 100644
--- a/test/test_objects.py
+++ b/test/test_objects.py
@@ -28,7 +28,7 @@ class _MockPullRequest:
 
 
 class Test_ChangeNote:
-    def test_from_pull_requests(self, caplog):
+    def test_from_pull_requests_multiple(self, caplog):
         caplog.set_level("DEBUG")
         body = """
 Some ignored text in the pull request body.
@@ -68,3 +68,24 @@ def test_from_pull_requests(self, caplog):
         assert len(caplog.records) == 1
         assert caplog.records[0].levelname == "DEBUG"
         assert "falling back to PR labels for summary" in caplog.records[0].msg
+
+    def test_from_pull_requests_fallback_title(self, caplog):
+        caplog.set_level("DEBUG")
+        pull_request = _MockPullRequest(
+            title='The title {label="ignored in title"}',
+            body="Nothing here.",
+            labels=[_MockLabel("Documentation")],
+        )
+        notes = ChangeNote.from_pull_requests(
+            [pull_request],
+            pr_summary_regex=DEFAULT_CONFIG["pr_summary_regex"],
+            pr_summary_label_regex=DEFAULT_CONFIG["pr_summary_label_regex"],
+        )
+        assert len(notes) == 1
+        notes = sorted(notes, key=lambda n: n.content)
+        assert notes[0].content == 'The title {label="ignored in title"}'
+        assert notes[0].labels == ("Documentation",)
+
+        assert len(caplog.records) == 1
+        assert caplog.records[0].levelname == "DEBUG"
+        assert "falling back to title" in caplog.records[0].msg

From d846fb191f6d72093ecfc2d3fc14ff3a37157495 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Lars=20Gr=C3=BCter?= <lagru@mailbox.org>
Date: Tue, 9 Jan 2024 17:22:20 +0100
Subject: [PATCH 14/16] Cleanup code

---
 src/changelist/_objects.py | 35 ++++++++++++++++++-----------------
 test/test_objects.py       |  4 ++++
 2 files changed, 22 insertions(+), 17 deletions(-)

diff --git a/src/changelist/_objects.py b/src/changelist/_objects.py
index 1d20f78..eb88cfa 100644
--- a/src/changelist/_objects.py
+++ b/src/changelist/_objects.py
@@ -51,15 +51,14 @@ def from_pull_requests(
                 matches := tuple(pr_summary_regex.finditer(pr.body))
             ):
                 logger.debug("falling back to title for %s", pr.html_url)
-                notes.add(
-                    cls(
-                        content=pr.title.strip(),
-                        reference_name=f"#{pr.number}",
-                        reference_url=pr.html_url,
-                        labels=pr_labels,
-                        timestamp=pr.merged_at,
-                    )
+                note = cls(
+                    content=pr.title.strip(),
+                    reference_name=f"#{pr.number}",
+                    reference_url=pr.html_url,
+                    labels=pr_labels,
+                    timestamp=pr.merged_at,
                 )
+                notes.add(note)
                 continue
 
             assert len(matches) >= 1
@@ -70,21 +69,23 @@ def from_pull_requests(
                     labels = tuple(
                         label.strip() for label in label_match["label"].split(",")
                     )
+                    # Remove label block
                     summary = pr_summary_label_regex.sub("", summary)
                 else:
                     logger.debug(
-                        "falling back to PR labels for summary in %s", pr.html_url
+                        "falling back to PR labels for summary '%r' in %s",
+                        summary,
+                        pr.html_url,
                     )
                     labels = pr_labels
-                notes.add(
-                    cls(
-                        content=summary.strip(),
-                        reference_name=f"#{pr.number}",
-                        reference_url=pr.html_url,
-                        labels=labels,
-                        timestamp=pr.merged_at,
-                    )
+                note = cls(
+                    content=summary.strip(),
+                    reference_name=f"#{pr.number}",
+                    reference_url=pr.html_url,
+                    labels=labels,
+                    timestamp=pr.merged_at,
                 )
+                notes.add(note)
         return notes
 
 
diff --git a/test/test_objects.py b/test/test_objects.py
index 3f6c9cf..18caf5a 100644
--- a/test/test_objects.py
+++ b/test/test_objects.py
@@ -14,11 +14,15 @@
 
 @dataclass
 class _MockLabel:
+    """Mocks github.Label.Label partially."""
+
     name: str
 
 
 @dataclass
 class _MockPullRequest:
+    """Mocks github.PullRequest.PullRequest partially."""
+
     title: str
     body: Union[str, None]
     labels: list[_MockLabel]

From daa21af2686a27dd53b9302a4d57c5bd5b49b71b Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Lars=20Gr=C3=BCter?= <lagru@mailbox.org>
Date: Sun, 21 Jan 2024 11:30:41 +0100
Subject: [PATCH 15/16] Document multiple summary feature in README

Attempts to make the usage of the new feature clearer.
---
 README.md | 31 ++++++++++++++++++++++++++++++-
 1 file changed, 30 insertions(+), 1 deletion(-)

diff --git a/README.md b/README.md
index 21b8696..94fb8da 100644
--- a/README.md
+++ b/README.md
@@ -10,6 +10,8 @@ https://github.com/scientific-python/changelist/blob/main/CHANGELOG.md.
 - Compile a list of pull requests, code authors, and reviewers between
   two given git commits.
 - Categorize pull requests into sections based on GitHub labels.
+- Override pull request titles with more descriptive summaries.
+- Document unrelated changes in a pull requests in separate summaries.
 
 _This project is currently in its alpha stage and might be incomplete or change a lot!_
 
@@ -33,9 +35,36 @@ changelist scientific-python/changelist v0.2.0 main
 
 This will list all pull requests, authors and reviewers that touched commits
 between `v0.2.0` and `main` (excluding `v0.2.0`).
-Pull requests are sorted into section according to the configuration in
+Pull requests are sorted into sections according to the configuration in
 `tool.changelist.label_section_map`.
 
+## Writing pull request summaries
+
+By default, changelist will fall back to the title of a pull request and its
+GitHub labels to sort it into the appropriate section. However, if you want
+longer summaries of your changes you can add a code block with the following
+form anywhere in the description of the pull request:
+
+    ```release-note
+    An ideally expressive description of the change that is included as
+    a single bullet point. Newlines are removed.
+    ```
+
+Sometimes pull requests introduce changes that should be listed in different
+sections. For that reason, a summary block like above can be used more than
+once. Additionally, you can add independent labels to each summary by adding a
+`{label="..."}` anywhere in the summary. These labels are sorted the same way
+as regular pull request labels are. E.g. the two summaries below will go into
+separate sections:
+
+    ```release-note {label="Bug fix"}
+    Make `is_odd()` work for negative numbers.
+    ```
+
+    ```release-note
+    Deprecate `ìs_odd`; use `not (x % 2)` instead! {label="API, Highlight"}
+    ```
+
 ## Configuration
 
 changelist can be configured from two sources, in order of precedence:

From 13a73034734ff9f71e200056d85ee3105deba62b Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Lars=20Gr=C3=BCter?= <lagru+github@mailbox.org>
Date: Tue, 30 Jan 2024 00:29:09 +0100
Subject: [PATCH 16/16] Apply suggestion

Co-authored-by: Stefan van der Walt <sjvdwalt@gmail.com>
---
 README.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/README.md b/README.md
index 94fb8da..668a622 100644
--- a/README.md
+++ b/README.md
@@ -50,7 +50,7 @@ form anywhere in the description of the pull request:
     a single bullet point. Newlines are removed.
     ```
 
-Sometimes pull requests introduce changes that should be listed in different
+Sometimes pull requests introduce multiple changes that should be listed in different
 sections. For that reason, a summary block like above can be used more than
 once. Additionally, you can add independent labels to each summary by adding a
 `{label="..."}` anywhere in the summary. These labels are sorted the same way