Fixed #37093 -- Clarified pull request instructions and adjusted error messages.

The intention is to reduce the perceived harshness of error messages so
that they look more like just a friendly list of things in your PR to
fix, especially for new contributors.

3 files changed, 11 insertions, 38 deletions

diff --git a/scripts/pr_quality/check_pr.py b/scripts/pr_quality/check_pr.py
index 2cf225a27a..272e003567 100644
--- a/scripts/pr_quality/check_pr.py
+++ b/scripts/pr_quality/check_pr.py
@@ -330,16 +330,7 @@ def check_pr_title_has_ticket(pr_title, ticket_id):
 
 
 def check_branch_description(pr_body):
-    """The branch description must be present.
-
-    The description should not contain the placeholder, and should be at least
-    5 words long.
-    """
-    placeholder = (
-        "Provide a concise overview of the issue or rationale behind the"
-        " proposed changes."
-    )
-
+    """The branch description should be at least 5 words long."""
     description_match = re.search(
         r"#### Branch description[ \t]*\r?\n(.*?)(?=\r?\n####|\Z)",
         pr_body,
@@ -351,7 +342,7 @@ def check_branch_description(pr_body):
     # Strip HTML comments before evaluating content.
     cleaned = strip_html_comments(description_match.group(1)).strip()
 
-    if not cleaned or placeholder in cleaned or len(cleaned.split()) < MIN_WORDS:
+    if not cleaned or len(cleaned.split()) < MIN_WORDS:
         return Message(*MISSING_DESCRIPTION)
 
     return None
diff --git a/scripts/pr_quality/errors.py b/scripts/pr_quality/errors.py
index cd41612da3..eb75b556f5 100644
--- a/scripts/pr_quality/errors.py
+++ b/scripts/pr_quality/errors.py
@@ -5,7 +5,7 @@ str.format() placeholders; kwargs are supplied at Message() construction time.
 
 """
 
-LEVEL_ERROR = ("🛑", "Error")
+LEVEL_ERROR = ("❗", "Error")
 LEVEL_WARNING = ("⚠️", "Warning")
 
 
@@ -112,9 +112,7 @@ MISSING_AI_DISCLOSURE = (
 
 MISSING_DESCRIPTION = (
     "Missing PR Description",
-    "Your PR description must be substantive and meaningful. The placeholder text "
-    '"*Provide a concise overview of the issue or rationale behind the proposed '
-    'changes.*" is not acceptable.\n\n'
+    "Your PR description must be substantive and meaningful.\n\n"
     "**What to do:**\n\n"
     "Write a description that contains at least 5 words and addresses:\n\n"
     "- What problem does this PR solve?\n"
diff --git a/scripts/pr_quality/tests/test_check_pr.py b/scripts/pr_quality/tests/test_check_pr.py
index 0aff15ca10..74b3350000 100644
--- a/scripts/pr_quality/tests/test_check_pr.py
+++ b/scripts/pr_quality/tests/test_check_pr.py
@@ -43,12 +43,13 @@ def make_pr_body(
         "This PR targets the `main` branch."
         " <!-- Backports will be evaluated and done by mergers, when necessary. -->",
         "The commit message is written in past tense, mentions the ticket"
-        " number, and ends with a period (see [guidelines]"
+        " number (if applicable), and ends with a period (see [guidelines]"
         "(https://docs.djangoproject.com/en/dev/internals/contributing/"
         "committing-code/#committing-guidelines)).",
         "I have not requested, and will not request, an automated AI review"
         " for this PR."
-        " <!-- You are welcome to do so in your own fork. -->",
+        " <!-- You are welcome to do so in your own fork. -->\n\n"
+        "<!-- Leave the following items unchecked if not applicable. -->",
         'I have checked the "Has patch" ticket flag in the Trac system.',
         "I have added or updated relevant tests.",
         "I have added or updated relevant docs, including release notes if"
@@ -73,10 +74,11 @@ def make_pr_body(
         f"{description}\n"
         f"\n"
         f"#### AI Assistance Disclosure (REQUIRED)\n"
-        f"<!-- Please select exactly ONE of the following: -->\n"
+        f"<!-- Select exactly ONE of the following: -->\n"
         f"- {no_ai_box} **No AI tools were used** in preparing this PR.\n"
         f"- {ai_used_box} **If AI tools were used**, I have disclosed which"
         f" ones, and fully reviewed and verified their output.{ai_extra}\n"
+        f"<!-- If AI tools were used, provide which tools were used here. -->\n"
         f"\n"
         f"#### Checklist\n"
         f"{checklist_lines}\n"
@@ -465,24 +467,6 @@ class TestCheckBranchDescription(BaseTestCase):
     def test_valid_passes(self):
         self.assertIsNone(check_pr.check_branch_description(VALID_PR_BODY))
 
-    def test_placeholder_fails(self):
-        body = make_pr_body(
-            description=(
-                "Provide a concise overview of the issue or rationale behind"
-                " the proposed changes."
-            )
-        )
-        self.assertIsNotNone(check_pr.check_branch_description(body))
-
-    def test_placeholder_with_appended_text_fails(self):
-        body = make_pr_body(
-            description=(
-                "Provide a concise overview of the issue or rationale behind"
-                " the proposed changes. Yes."
-            )
-        )
-        self.assertIsNotNone(check_pr.check_branch_description(body))
-
     def test_empty_fails(self):
         body = make_pr_body(description="")
         self.assertIsNotNone(check_pr.check_branch_description(body))
@@ -688,8 +672,8 @@ class TestIntegration(BaseTestCase):
         blank_body = make_pr_body(
             ticket="ticket-XXXXX",
             description=(
-                "Provide a concise overview of the issue or rationale behind"
-                " the proposed changes."
+                "<!-- Provide a concise overview of the issue or rationale behind"
+                " the proposed changes. 5 word minimum. -->"
             ),
             no_ai_checked=False,
             ai_used_checked=False,