[Django] #37093: Adjust GitHub PR description template + bot check error emoji

[Django]

#37093: Adjust GitHub PR description template + bot check error emoji
-------------------------------------+-------------------------------------
Reporter: Stephanie Goulet | Type:
| Cleanup/optimization
Status: new | Component:
| Uncategorized
Version: 6.0 | Severity: Normal
Keywords: PR, GitHub | Triage Stage:
| Unreviewed
Has patch: 0 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 0 | UI/UX: 0
-------------------------------------+-------------------------------------
The below suggestions are based on the forum discussion,
[https://forum.djangoproject.com/t/bot-checks-for-typo-prs-some-
considerations/45028 Bot checks for typo PRs (some considerations)].

**Suggestion 1: Adjust GitHub PR description template**
When opening my first [https://github.com/django/django/pull/21195 PR for
a typo fix], I ran into a little confusion which resulted in an auto-
closed PR that might've been avoided with some small adjustments.

I propose the following edits to the PR description template to improve
clarity, particularly for new contributors.

The full current and proposed templates are below, however for
convenience, you can see the differences more easily in this
[https://www.diffchecker.com/Eba3oc1t/ saved diff].

Current template:
{{{
#### Trac ticket number
<!-- Replace XXXXX with the corresponding Trac ticket number. -->
<!-- Or delete the line and write "N/A - typo" for typo fixes. -->

ticket-XXXXX

#### Branch description
Provide a concise overview of the issue or rationale behind the proposed
changes.

#### AI Assistance Disclosure (REQUIRED)
<!-- Please select exactly ONE of the following: -->
- [ ] **No AI tools were used** in preparing this PR.
- [ ] **If AI tools were used**, I have disclosed which ones, and fully
reviewed and verified their output.

#### Checklist
- [ ] This PR follows the [contribution
guidelines](https://docs.djangoproject.com/en/stable/internals/contributing
/writing-code/submitting-patches/).
- [ ] This PR **does not** disclose a security vulnerability (see
[vulnerability
reporting](https://docs.djangoproject.com/en/stable/internals/security/)).
- [ ] 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](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. -->
- [ ] 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
applicable.
- [ ] I have attached screenshots in both light and dark modes for any UI
changes.
}}}

Proposed template:
{{{
#### Trac ticket number
<!-- Replace XXXXX with the corresponding Trac ticket number. -->
<!-- Or delete the line and write "N/A - typo" for typo fixes. -->

ticket-XXXXX

#### Branch description
<!-- Provide a concise overview of the issue or rationale behind the
proposed changes. 5 word minimum. -->


#### AI Assistance Disclosure (REQUIRED)
<!-- Please select exactly ONE of the following: -->
- [ ] **No AI tools were used** in preparing this PR.
- [ ] **If AI tools were used**, I have disclosed which ones, and fully
reviewed and verified their output.

#### Checklist
<!-- Please leave non-applicable items unchecked. -->

- [ ] This PR follows the [contribution
guidelines](https://docs.djangoproject.com/en/stable/internals/contributing
/writing-code/submitting-patches/).
- [ ] This PR **does not** disclose a security vulnerability (see
[vulnerability
reporting](https://docs.djangoproject.com/en/stable/internals/security/)).
- [ ] 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 (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. -->
- [ ] 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
applicable.
- [ ] I have attached screenshots in both light and dark modes for any UI
changes.
}}}

----

**Suggestion 2: Remove the stop sign emojis from the bot check error
messages**

I propose replacing the [https://emojis.wiki/stop-sign/ :stop_sign:] emoji
that is shown in the PR bot check error messages with the
[https://emojis.wiki/right-arrow/ :right_arrow:] emoji to keep the list of
errors eye-catching while neutralizing the color so as to reduce the
likelihood for contributors (especially new contributors) to read the
bright red stop sign as a little harsh. I believe the inclusion of "Error"
before each error description as well as the fact that the PR is
automatically closed is sufficiently clear to communicate that those
errors need to be addressed for the PR to be reconsidered.

Alternatively, if the specific emoji replacement of [https://emojis.wiki
/right-arrow/ :right_arrow:] is undesired, I propose removing the
[https://emojis.wiki/stop-sign/ :stop_sign:] emoji without a replacement
for the same reasons as above. This alternative might be more appropriate
if we highly value errors only ever being exclusively associated with the
color red, but still see value in reducing the harshness factor. The trade
off is that this loses the eye-catching factor of having an emoji next to
the error titles which is particularly helpful when first seeing the auto
response because the list is automatically expanded (rightfully so, in my
opinion) despite each error header being expandable/collapsible.

For the record, I'm also open to other emoji options as an alternative to
the stop sign but tried to pick the one I thought was best keeping in mind
the feedback in the forum comments (e.g. staying away from yellow/orange,
etc.) to make this a clearer proposed edit to review.

See this
[https://github.com/django/django/pull/21195#issuecomment-4352103892 bot-
closed PR comment] as an example of where the stop sign emojis appear.
--
Ticket URL: <https://code.djangoproject.com/ticket/37093>
Django <https://code.djangoproject.com/>
The Web framework for perfectionists with deadlines.

[Django]

#37093: Adjust GitHub PR description template + bot check error emoji
-------------------------------------+-------------------------------------

Reporter: Stephanie Goulet | Owner: (none)
Type: | Status: new
Cleanup/optimization |
Component: Uncategorized | Version: 6.0
Severity: Normal | Resolution:

Keywords: PR, GitHub | Triage Stage:
| Unreviewed
Has patch: 0 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 0 | UI/UX: 0
-------------------------------------+-------------------------------------

Changes (by Tim Schilling):

* cc: Tim Schilling (added)

--
Ticket URL: <https://code.djangoproject.com/ticket/37093#comment:1>

[Django]

#37093: Adjust GitHub PR description template + bot check error emoji

--------------------------------------+------------------------------------

Reporter: Stephanie Goulet | Owner: (none)

Type: Cleanup/optimization | Status: new
Component: Core (Other) | Version: 6.0
Severity: Normal | Resolution:
Keywords: PR, GitHub | Triage Stage: Accepted

Has patch: 0 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 0 | UI/UX: 0

--------------------------------------+------------------------------------
Changes (by Jacob Walls):

* component: Uncategorized => Core (Other)
* stage: Unreviewed => Accepted

Comment:

Thanks for the thoughtful ticket and suggested edits. Accepting.

A note: the automated PR quality check
[https://github.com/django/django/blob/4d455ae2d7689ce066dfffef9fc29a6f6d3ed33e/scripts/pr_quality/check_pr.py#L410
expects only the last two checkboxes to be optional], so I would suggest
making that explicit in the checklist somehow.

Just before those two items, maybe:
"Leave the following items unchecked if not applicable:"

Are you interested in submitting a PR?
--
Ticket URL: <https://code.djangoproject.com/ticket/37093#comment:2>

[Django]

#37093: Adjust GitHub PR description template + bot check error emoji
--------------------------------------+------------------------------------
Reporter: Stephanie Goulet | Owner: (none)
Type: Cleanup/optimization | Status: new
Component: Core (Other) | Version: 6.0
Severity: Normal | Resolution:
Keywords: PR, GitHub | Triage Stage: Accepted
Has patch: 0 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 0 | UI/UX: 0
--------------------------------------+------------------------------------

Comment (by blighj):

Replying to [comment:2 Jacob Walls]:

> A note: the automated PR quality check
[https://github.com/django/django/blob/4d455ae2d7689ce066dfffef9fc29a6f6d3ed33e/scripts/pr_quality/check_pr.py#L410
expects only the last two checkboxes to be optional], so I would suggest
making that explicit in the checklist somehow.

My understanding was that the bot is checking the first five are checked,
which would make it the last four, not the last two, that the bot sees as
optional.

I'm open to being corrected on that, but it looks right from the code and
those last four being if applicable makes sense
--
Ticket URL: <https://code.djangoproject.com/ticket/37093#comment:3>

[Django]

#37093: Adjust GitHub PR description template + bot check error emoji
--------------------------------------+------------------------------------
Reporter: Stephanie Goulet | Owner: (none)
Type: Cleanup/optimization | Status: new
Component: Core (Other) | Version: 6.0
Severity: Normal | Resolution:
Keywords: PR, GitHub | Triage Stage: Accepted
Has patch: 0 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 0 | UI/UX: 0
--------------------------------------+------------------------------------

Comment (by Stephanie Goulet):

Replying to [comment:2 Jacob Walls]:

> Are you interested in submitting a PR?

Sure, I can try

Based on what's been said so far: [https://www.diffchecker.com/EiWV1Bg9/
Updated V2 of draft edits].
- Added as a comment but before the last four items instead of two (blighj
seems right to me but let me know if I'm misunderstanding anything)
- Also removed the "please" in the AI section for consistency across all
the comment instructions

Had another thought which is one thing that moving the branch description
to a comment does is make it so the comment will remain in submitted PRs.
This is consistent with other sections having comments so maybe it doesn't
matter, but if the reviewers care to keep it as not having a comment in
the branch description for submitted PRs, an alternative edit could be:

Update the section to be:
{{{
#### Branch description
Replace this text with a concise overview of the issue or rationale behind
the proposed changes (5 word minimum).
}}}

Which would also require updating the
[https://github.com/django/django/blob/4d455ae2d7689ce066dfffef9fc29a6f6d3ed33e/scripts/pr_quality/check_pr.py#L332
branch description check] just so that the placeholder text is matching
against the new version of the placeholder text.
--
Ticket URL: <https://code.djangoproject.com/ticket/37093#comment:4>

[Django]

#37093: Adjust GitHub PR description template + bot check error emoji
--------------------------------------+------------------------------------
Reporter: Stephanie Goulet | Owner: (none)
Type: Cleanup/optimization | Status: new
Component: Core (Other) | Version: 6.0
Severity: Normal | Resolution:
Keywords: PR, GitHub | Triage Stage: Accepted
Has patch: 0 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 0 | UI/UX: 0
--------------------------------------+------------------------------------

Comment (by Jacob Walls):

I like the idea of moving the placeholder to a comment. We could leave the
branch description check in place in case we think any models have trained
on it, but just leave a comment explaining it's no longer in use. Happy to
look at a PR!
--
Ticket URL: <https://code.djangoproject.com/ticket/37093#comment:5>

[Django]

#37093: Adjust GitHub PR description template + bot check error emoji
--------------------------------------+------------------------------------
Reporter: Stephanie Goulet | Owner: (none)
Type: Cleanup/optimization | Status: new
Component: Core (Other) | Version: 6.0
Severity: Normal | Resolution:
Keywords: PR, GitHub | Triage Stage: Accepted
Has patch: 0 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 0 | UI/UX: 0
--------------------------------------+------------------------------------

Changes (by Raffaella):

* cc: Raffaella (added)

--
Ticket URL: <https://code.djangoproject.com/ticket/37093#comment:6>

[Django]

#37093: Adjust GitHub PR description template + bot check error emoji
--------------------------------------+------------------------------------
Reporter: Stephanie Goulet | Owner: (none)
Type: Cleanup/optimization | Status: new
Component: Core (Other) | Version: 6.0
Severity: Normal | Resolution:
Keywords: PR, GitHub | Triage Stage: Accepted
Has patch: 0 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 0 | UI/UX: 0
--------------------------------------+------------------------------------

Comment (by Stephanie Goulet):

To clarify, re:

> I like the idea of moving the placeholder to a comment. We could leave
the branch description check in place in case we think any models have
trained on it, but just leave a comment explaining it's no longer in use.

Going with moving the placeholder to a comment means the branch
description check can not be changed and would still be in use anyway
though, right? So no comment explaining it's not in use seems necessary
(unless I'm misunderstanding what you mean?)

Re: PR - grateful for your patience as I work through the new contributor
guide
--
Ticket URL: <https://code.djangoproject.com/ticket/37093#comment:7>

[Django]

#37093: Adjust GitHub PR description template + bot check error emoji
--------------------------------------+------------------------------------
Reporter: Stephanie Goulet | Owner: (none)
Type: Cleanup/optimization | Status: new
Component: Core (Other) | Version: 6.0
Severity: Normal | Resolution:
Keywords: PR, GitHub | Triage Stage: Accepted
Has patch: 0 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 0 | UI/UX: 0
--------------------------------------+------------------------------------
Comment (by Stephanie Goulet):

Oh wait, I think I get what you're saying now (like, the check would still
run regardless, but you're saying half of it becomes pointless since the
template placeholder is now a comment which is stripped before evaluating
in the check so it automatically wouldn't fail that part if a human uses
the template (which of course a human will). But you don't want to remove
that part of the check because an AI will maybe submit the placeholder
text anyway due to its previous/outdated training)

Can disregard the previous clarification unless I'm off the mark above; I
think I understand enough of what you want to do the PR
--
Ticket URL: <https://code.djangoproject.com/ticket/37093#comment:8>

[Django]

#37093: Adjust GitHub PR description template + bot check error emoji
--------------------------------------+------------------------------------
Reporter: Stephanie Goulet | Owner: (none)
Type: Cleanup/optimization | Status: new
Component: Core (Other) | Version: 6.0
Severity: Normal | Resolution:
Keywords: PR, GitHub | Triage Stage: Accepted
Has patch: 0 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 0 | UI/UX: 0
--------------------------------------+------------------------------------

Comment (by Jacob Walls):

Exactly! Sorry for the brevity...
--
Ticket URL: <https://code.djangoproject.com/ticket/37093#comment:9>