ci: enforce double backticks in release notes via pre-commit hook (#11562)

Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: julian-risch

.pre-commit-config.yaml

@@ -35,6 +35,13 @@ repos:
           - ruff
           - add-trailing-comma
 
+      - id: release-note-backticks
+        name: release-note-backticks
+        language: python
+        entry: python scripts/release_note_backticks.py
+        files: ^releasenotes/notes/.*\.yaml$
+        types: [text]
+
   - repo: https://github.com/codespell-project/codespell
     rev: v2.4.1
     hooks:

scripts/release_note_backticks.py

@@ -0,0 +1,60 @@
+# SPDX-FileCopyrightText: 2022-present deepset GmbH <info@deepset.ai>
+#
+# SPDX-License-Identifier: Apache-2.0
+
+"""
+Pre-commit hook that enforces reStructuredText inline-code syntax in reno release notes.
+
+Release notes under ``releasenotes/notes/*.yaml`` are rendered as reStructuredText, where inline
+code must use double backticks (``like_this``). A common mistake is to use Markdown-style single
+backticks (`like_this`), which RST renders as italic "interpreted text" instead of code.
+
+By default the hook rewrites single backticks to double backticks and exits non-zero when it
+changes a file, so the rewrite can be reviewed before re-staging; ``--check`` only reports.
+It leaves existing double backticks ``code`` untouched and skips RST roles (:func:`x`) and
+hyperlink references (`text <url>`_).
+"""
+
+import argparse
+import re
+import sys
+
+# A single-backtick inline-code span that should use double backticks. The look-arounds skip
+# valid RST: ``...`` pairs (the backtick-adjacent guards), roles like :func:`x` (no ':' before
+# the opening backtick), and hyperlink refs like `text <url>`_ (no '_' after the closing one).
+SINGLE_BACKTICK_RE = re.compile(r"(?<![`:])`(?!`)([^`\n]+?)`(?![`_])")
+
+
+def fix_text(text: str) -> str:
+    """Return ``text`` with single-backtick inline code rewritten to double backticks."""
+    return SINGLE_BACKTICK_RE.sub(r"``\1``", text)
+
+
+def main() -> int:
+    """Entry point for the pre-commit hook."""
+    parser = argparse.ArgumentParser(description="Enforce double backticks in reno release notes.")
+    parser.add_argument("--check", action="store_true", help="Report problems without modifying files.")
+    parser.add_argument("files", nargs="*")
+    args = parser.parse_args()
+
+    ret = 0
+    for path in args.files:
+        with open(path, encoding="utf-8") as f:
+            original = f.read()
+        fixed = fix_text(original)
+        if fixed == original:
+            continue
+        ret = 1
+        print(f"{'single backtick in' if args.check else 'fixed'}: {path}", file=sys.stderr)
+        if not args.check:
+            with open(path, "w", encoding="utf-8") as f:
+                f.write(fixed)
+
+    if ret:
+        hint = "Run without --check to fix automatically." if args.check else "Review and re-stage the changes."
+        print(f"\nrelease notes need double backticks (``like_this``) for inline code. {hint}", file=sys.stderr)
+    return ret
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

test/test_release_note_backticks.py

@@ -0,0 +1,90 @@
+# SPDX-FileCopyrightText: 2022-present deepset GmbH <info@deepset.ai>
+#
+# SPDX-License-Identifier: Apache-2.0
+
+import importlib.util
+import subprocess
+import sys
+from pathlib import Path
+
+import pytest
+
+_SCRIPT = Path(__file__).resolve().parents[1] / "scripts" / "release_note_backticks.py"
+_spec = importlib.util.spec_from_file_location("release_note_backticks", _SCRIPT)
+_module = importlib.util.module_from_spec(_spec)
+_spec.loader.exec_module(_module)
+fix_text = _module.fix_text
+
+
+class TestFixText:
+    @pytest.mark.parametrize(
+        "text, expected",
+        [
+            ("Use `OpenAIChatGenerator` now.", "Use ``OpenAIChatGenerator`` now."),
+            ("Set `api_key` and `azure_endpoint`.", "Set ``api_key`` and ``azure_endpoint``."),
+            ('Call `Secret.from_env_var("X")`.', 'Call ``Secret.from_env_var("X")``.'),
+            ("Leading `code` token.", "Leading ``code`` token."),
+        ],
+    )
+    def test_converts_single_to_double(self, text, expected):
+        assert fix_text(text) == expected
+
+    @pytest.mark.parametrize(
+        "text",
+        [
+            "Already correct: ``OpenAIChatGenerator``.",
+            "Two literals ``Secret`` and ``api_key``.",
+            "No inline code at all here.",
+            "RST role :func:`do_thing` must stay single.",
+            "Link `Haystack <https://haystack.deepset.ai>`_ must stay single.",
+        ],
+    )
+    def test_leaves_valid_rst_untouched(self, text):
+        assert fix_text(text) == text
+
+    def test_only_single_backticks_in_mixed_text_are_converted(self):
+        text = "Use ``Secret`` for `api_key` and `azure_endpoint`."
+        expected = "Use ``Secret`` for ``api_key`` and ``azure_endpoint``."
+        assert fix_text(text) == expected
+
+    def test_is_idempotent(self):
+        once = fix_text("Set `x` and `y`.")
+        assert fix_text(once) == once
+
+    def test_unbalanced_single_backtick_is_left_untouched(self):
+        # A stray, unpaired backtick is ambiguous, so we never rewrite it.
+        text = "An unbalanced `backtick stays as is.\n"
+        assert fix_text(text) == text
+
+
+class TestCli:
+    def test_fix_rewrites_file_and_is_idempotent(self, tmp_path):
+        note = tmp_path / "note.yaml"
+        note.write_text("enhancements:\n  - |\n    Use `Foo` and `Bar` now.\n", encoding="utf-8")
+
+        first = subprocess.run([sys.executable, str(_SCRIPT), str(note)], capture_output=True, text=True, check=False)
+        assert first.returncode == 1
+        assert "``Foo``" in note.read_text(encoding="utf-8")
+        assert "``Bar``" in note.read_text(encoding="utf-8")
+
+        # Running again on the now-fixed file is a no-op and succeeds.
+        second = subprocess.run([sys.executable, str(_SCRIPT), str(note)], capture_output=True, text=True, check=False)
+        assert second.returncode == 0
+
+    def test_check_mode_reports_without_modifying(self, tmp_path):
+        note = tmp_path / "note.yaml"
+        content = "enhancements:\n  - |\n    Use `Foo` now.\n"
+        note.write_text(content, encoding="utf-8")
+
+        result = subprocess.run(
+            [sys.executable, str(_SCRIPT), "--check", str(note)], capture_output=True, text=True, check=False
+        )
+        assert result.returncode == 1
+        assert note.read_text(encoding="utf-8") == content
+
+    def test_clean_file_passes(self, tmp_path):
+        note = tmp_path / "note.yaml"
+        note.write_text("enhancements:\n  - |\n    Use ``Foo`` now.\n", encoding="utf-8")
+
+        result = subprocess.run([sys.executable, str(_SCRIPT), str(note)], capture_output=True, text=True, check=False)
+        assert result.returncode == 0