[clang-tools-extra] [clang-tidy] Give clear instruction when duplicates are detected in `check_alphabetical_order.py` (PR #173465)

[via cfe-commits]

https://github.com/zeyi2 created https://github.com/llvm/llvm-project/pull/173465

As of AI usage: Gemini 3 is used to generate the new instruction.

Related discussion: https://github.com/llvm/llvm-project/pull/173448#discussion_r2644988250

>From 69412fdc26e650403728fd0ca002ee5894f82697 Mon Sep 17 00:00:00 2001
From: mtx <mitchell.xu2 at gmail.com>
Date: Wed, 24 Dec 2025 15:45:42 +0800
Subject: [PATCH] [clang-tidy] Give clear instruction when duplicates are
 detected in check_alphabetical_order.py

---
 .../clang-tidy/tool/check_alphabetical_order.py           | 3 ++-
 .../clang-tidy/tool/check_alphabetical_order_test.py      | 8 ++++++--
 2 files changed, 8 insertions(+), 3 deletions(-)

diff --git a/clang-tools-extra/clang-tidy/tool/check_alphabetical_order.py b/clang-tools-extra/clang-tidy/tool/check_alphabetical_order.py
index 66819aba435e8..6a200e36b2715 100644
--- a/clang-tools-extra/clang-tidy/tool/check_alphabetical_order.py
+++ b/clang-tools-extra/clang-tidy/tool/check_alphabetical_order.py
@@ -352,7 +352,8 @@ def _emit_duplicate_report(lines: Sequence[str], title: str) -> Optional[str]:
     if not (dups_detail := find_duplicate_entries(lines, title)):
         return None
     out: List[str] = []
-    out.append(f"Error: Duplicate entries in '{title}':\n")
+    out.append(f"Error: Duplicate entries in '{title}'.\n")
+    out.append("\nPlease merge these entries into a single bullet point.\n")
     for key, occs in dups_detail:
         out.append(f"\n-- Duplicate: {key}\n")
         for start_idx, block in occs:
diff --git a/clang-tools-extra/clang-tidy/tool/check_alphabetical_order_test.py b/clang-tools-extra/clang-tidy/tool/check_alphabetical_order_test.py
index 48a3c761c12ce..fa418e41ee8a8 100644
--- a/clang-tools-extra/clang-tidy/tool/check_alphabetical_order_test.py
+++ b/clang-tools-extra/clang-tidy/tool/check_alphabetical_order_test.py
@@ -92,7 +92,9 @@ def test_duplicate_detection_and_report(self) -> None:
 
         expected_report = textwrap.dedent(
             """\
-            Error: Duplicate entries in 'Changes in existing checks':
+            Error: Duplicate entries in 'Changes in existing checks'.
+
+            Please merge these entries into a single bullet point.
 
             -- Duplicate: - Improved :doc:`bugprone-easily-swappable-parameters
 
@@ -269,7 +271,9 @@ def test_process_release_notes_with_duplicates_fails(self) -> None:
             self.assertEqual(rc, 3)
             expected_report = textwrap.dedent(
                 """\
-                Error: Duplicate entries in 'Changes in existing checks':
+                Error: Duplicate entries in 'Changes in existing checks'.
+
+                Please merge these entries into a single bullet point.
 
                 -- Duplicate: - Improved :doc:`bugprone-easily-swappable-parameters