[Django] #27392: Remove "Tests that", "Ensures that", etc. from test docstings
Django
------------------------------------------------+------------------------
Reporter: Tim Graham | Owner: nobody
Type: Cleanup/optimization | Status: new
Component: Documentation | Version: master
Severity: Normal | Keywords:
Triage Stage: Accepted | Has patch: 0
Needs documentation: 0 | Needs tests: 0
Patch needs improvement: 0 | Easy pickings: 1
UI/UX: 0 |
------------------------------------------------+------------------------
Our policy is for test docstrings to state the expected behavior that each
test demonstrates. Preambles such as "Tests that" or "Ensures that" aren't
necessary.
Good: "Horizontal and vertical filter widgets keep selected options on
page reload."
Bad: "Tests that horizontal and vertical...".
For example:
$ grep -rI "Tests that" * | wc -l
158
$ grep -rI "Test that" * | wc -l
222
$ grep -rI "Ensure that" * | wc -l
173
$ grep -rI "Ensures that" * | wc -l
14
If you spot any other similar patterns, please correct them. The policy
should also be added to `docs/internals/contributing/writing-code/coding-
style.txt`.
--
Ticket URL: <https://code.djangoproject.com/ticket/27392>
Django <https://code.djangoproject.com/>
The Web framework for perfectionists with deadlines.
Django
Reporter: Tim Graham | Owner: za
Type: Cleanup/optimization | Status: assigned
Component: Documentation | Version: master
Severity: Normal | Resolution:
Keywords: | Triage Stage: Accepted
Has patch: 0 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 1 | UI/UX: 0
Changes (by za):
* status: new => assigned
* owner: nobody => za
--
Ticket URL: <https://code.djangoproject.com/ticket/27392#comment:1>
Django
Reporter: Tim Graham | Owner: Mahendra
Type: | Yadav
Cleanup/optimization | Status: assigned
Component: Documentation | Version: master
Severity: Normal | Resolution:
Keywords: | Triage Stage: Accepted
Has patch: 0 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 1 | UI/UX: 0
Changes (by Mahendra Yadav):
* owner: za => Mahendra Yadav
--
Ticket URL: <https://code.djangoproject.com/ticket/27392#comment:2>
Django
Reporter: Tim Graham | Owner: Mahendra
Type: | Yadav
Cleanup/optimization | Status: assigned
Severity: Normal | Resolution:
Keywords: | Triage Stage: Accepted
Has patch: 0 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 1 | UI/UX: 0
Comment (by Tim Graham):
Another phrasing to remove is "Checks that" / "Check that".
A [https://github.com/django/django/pull/7439 PR] is started by za.
--
Ticket URL: <https://code.djangoproject.com/ticket/27392#comment:3>
Django
Reporter: Tim Graham | Owner: za
Type: Cleanup/optimization | Status: assigned
Severity: Normal | Resolution:
Keywords: | Triage Stage: Accepted
Has patch: 0 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 1 | UI/UX: 0
Changes (by za):
* owner: Mahendra Yadav => za
Comment:
@Mahendra Yadav: currently I'm working on
[https://github.com/django/django/pull/7439 PR 7439].
--
Ticket URL: <https://code.djangoproject.com/ticket/27392#comment:4>
Django
Reporter: Tim Graham | Owner: za
Type: Cleanup/optimization | Status: assigned
Severity: Normal | Resolution:
Keywords: | Triage Stage: Accepted
Has patch: 1 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 1 | UI/UX: 0
Changes (by Tim Graham):
* has_patch: 0 => 1
--
Ticket URL: <https://code.djangoproject.com/ticket/27392#comment:5>
Django
Reporter: Tim Graham | Owner: za
Type: Cleanup/optimization | Status: assigned
Severity: Normal | Resolution:
Keywords: | Triage Stage: Accepted
Has patch: 1 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 1
Easy pickings: 1 | UI/UX: 0
Changes (by Reinout van Rees):
* cc: reinout@… (added)
* needs_better_patch: 0 => 1
Comment:
Marked the ticket as "patch needs improvement", see
https://github.com/django/django/pull/7439#issuecomment-258603274
Mostly "just" re-running regexes with similar occurrences.
--
Ticket URL: <https://code.djangoproject.com/ticket/27392#comment:6>
Django
Reporter: Tim Graham | Owner: za
Type: Cleanup/optimization | Status: assigned
Severity: Normal | Resolution:
Keywords: | Triage Stage: Accepted
Has patch: 1 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 1
Easy pickings: 1 | UI/UX: 0
Comment (by Tim Graham <timograham@…>):
In [changeset:"321e94fa41b121f65c02119c02098df327bbd569" 321e94fa]:
{{{
#!CommitTicketReference repository=""
revision="321e94fa41b121f65c02119c02098df327bbd569"
Refs #27392 -- Removed "Tests that", "Ensures that", etc. from test
docstrings.
}}}
--
Ticket URL: <https://code.djangoproject.com/ticket/27392#comment:7>
Django
Reporter: Tim Graham | Owner: za
Type: Cleanup/optimization | Status: assigned
Severity: Normal | Resolution:
Keywords: | Triage Stage: Accepted
Has patch: 0 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 1 | UI/UX: 0
Changes (by Tim Graham):
* needs_better_patch: 1 => 0
* has_patch: 1 => 0
Comment:
While reviewing the patch, I came across additional phrases that could be
removed. There are probably more variants as well:
Tests if
Ensured that
Tests whether
Ensure
Make sure
Confirms that
Makes sure
Check to
Check we
Ensure the
Test
--
Ticket URL: <https://code.djangoproject.com/ticket/27392#comment:8>
Django
Reporter: Tim Graham | Owner: za
Type: Cleanup/optimization | Status: assigned
Severity: Normal | Resolution:
Keywords: | Triage Stage: Accepted
Has patch: 0 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 1 | UI/UX: 0
Comment (by Barun Parruck):
Hi! I was thinking of working on this. Two questions --
1. Do you want something like "Tests adding a FK constraint for an
existing column" to go to "Adds foreign key constraint to an existing
column", or "Foreign key constraint can be added to an existing column".
2. Secondly, could I create a simple pull request with only ~10 or so
fixes to get the hang of the development workflow? (To make sure I'm doing
the right thing!)
--
Ticket URL: <https://code.djangoproject.com/ticket/27392#comment:9>
Django
Reporter: Tim Graham | Owner: za
Type: Cleanup/optimization | Status: assigned
Severity: Normal | Resolution:
Keywords: | Triage Stage: Accepted
Has patch: 0 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 1 | UI/UX: 0
Comment (by Tim Graham):
For the "Tests adding" case, I'd just chop "Test". It's okay to make a
work-in-progress PR.
--
Ticket URL: <https://code.djangoproject.com/ticket/27392#comment:10>
Django
Reporter: Tim Graham | Owner: alisye
Type: Cleanup/optimization | Status: assigned
Component: Documentation | Version: master
Severity: Normal | Resolution:
Keywords: | Triage Stage: Accepted
Has patch: 0 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 1 | UI/UX: 0
Changes (by alisye):
* owner: za => alisye
--
Ticket URL: <https://code.djangoproject.com/ticket/27392#comment:11>
Django
Reporter: Tim Graham | Owner: (none)
Type: Cleanup/optimization | Status: new
Component: Documentation | Version: master
Keywords: | Triage Stage: Accepted
Has patch: 0 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 1 | UI/UX: 0
Changes (by alisye):
* status: assigned => new
* owner: alisye => (none)
--
Ticket URL: <https://code.djangoproject.com/ticket/27392#comment:12>
Django
Reporter: Tim Graham | Owner: ablyx
Type: Cleanup/optimization | Status: assigned
Component: Documentation | Version: master
Severity: Normal | Resolution:
Keywords: | Triage Stage: Accepted
Has patch: 0 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 1 | UI/UX: 0
Changes (by ablyx):
* owner: (none) => ablyx
* status: new => assigned
--
Ticket URL: <https://code.djangoproject.com/ticket/27392#comment:13>
Django
Reporter: Tim Graham | Owner: (none)
Type: Cleanup/optimization | Status: new
Component: Documentation | Version: master
Keywords: | Triage Stage: Accepted
Has patch: 0 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 1 | UI/UX: 0
Changes (by ablyx):
* status: assigned => new
* owner: ablyx => (none)
--
Ticket URL: <https://code.djangoproject.com/ticket/27392#comment:14>
Django
Reporter: Tim Graham | Owner: Eric
Type: | Linden
Cleanup/optimization | Status: assigned
Component: Documentation | Version: master
Severity: Normal | Resolution:
Keywords: | Triage Stage: Accepted
Has patch: 0 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 1 | UI/UX: 0
Changes (by Eric Linden):
* owner: (none) => Eric Linden
* status: new => assigned
--
Ticket URL: <https://code.djangoproject.com/ticket/27392#comment:13>
Django
Reporter: Tim Graham | Owner: Eric
Type: | Linden
Cleanup/optimization | Status: assigned
Severity: Normal | Resolution:
Keywords: | Triage Stage: Accepted
Has patch: 0 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 1 | UI/UX: 0
Changes (by Eric Linden):
* cc: coralvanda@… (added)
Comment:
There are plenty of 'regression test for #xxx' and similar things. Should
those be left as is, modified to keep the reference to the fact that it's
a regression test, or just get rid of that type of statement?
--
Ticket URL: <https://code.djangoproject.com/ticket/27392#comment:14>
Django
Reporter: Tim Graham | Owner: Eric
Type: | Linden
Cleanup/optimization | Status: assigned
Severity: Normal | Resolution:
Keywords: | Triage Stage: Accepted
Has patch: 0 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 1 | UI/UX: 0
Comment (by Tim Graham):
We use a ticket reference for obscure issues that can't be described in a
docstring. Some places could be cleaned up but I wouldn't make it part of
this ticket. It would be better to wait a bit before working on this, as
described in an open [https://github.com/django/django/pull/7777 PR].
--
Ticket URL: <https://code.djangoproject.com/ticket/27392#comment:15>
Django
Reporter: Tim Graham | Owner: (none)
Component: Documentation | Version: master
Keywords: | Triage Stage: Accepted
Has patch: 0 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 1 | UI/UX: 0
Changes (by Eric Linden):
* cc: coralvanda@… (removed)
* owner: Eric Linden => (none)
* status: assigned => new
--
Ticket URL: <https://code.djangoproject.com/ticket/27392#comment:16>
Django
Reporter: Tim Graham | Owner: Jani
Type: | Sumak
Cleanup/optimization | Status: assigned
Component: Documentation | Version: master
Severity: Normal | Resolution:
Keywords: | Triage Stage: Accepted
Has patch: 0 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 1 | UI/UX: 0
Changes (by Jani Sumak):
* status: new => assigned
* owner: (none) => Jani Sumak
--
Ticket URL: <https://code.djangoproject.com/ticket/27392#comment:17>
Django
Reporter: Tim Graham | Owner: Zach
Type: | Zundel
Cleanup/optimization | Status: assigned
Component: Documentation | Version: master
Severity: Normal | Resolution:
Keywords: | Triage Stage: Accepted
Has patch: 0 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 1 | UI/UX: 0
Changes (by Zach Zundel):
* status: new => assigned
* owner: (none) => Zach Zundel
--
Ticket URL: <https://code.djangoproject.com/ticket/27392#comment:17>
Django
Reporter: Tim Graham | Owner: Roman
Type: | Dmytriv
Cleanup/optimization | Status: assigned
Component: Documentation | Version: master
Severity: Normal | Resolution:
Keywords: | Triage Stage: Accepted
Has patch: 0 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 1 | UI/UX: 0
Changes (by Roman Dmytriv):
* status: new => assigned
* owner: (none) => Roman Dmytriv
--
Ticket URL: <https://code.djangoproject.com/ticket/27392#comment:17>
Django
Reporter: Tim Graham | Owner: Roman
Type: | Dmytriv
Cleanup/optimization | Status: assigned
Severity: Normal | Resolution:
Keywords: | Triage Stage: Accepted
Has patch: 0 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 1 | UI/UX: 0
Changes (by Diogo Monteiro):
* cc: diogo.monteiro12@… (added)
--
Ticket URL: <https://code.djangoproject.com/ticket/27392#comment:18>
Django
Reporter: Tim Graham | Owner: Roman
Type: | Dmytriv
Cleanup/optimization | Status: assigned
Severity: Normal | Resolution:
Keywords: | Triage Stage: Accepted
Has patch: 0 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 1 | UI/UX: 0
Comment (by Theofanis Despoudis):
Is this Ticket worked on?. The PR listed here
https://github.com/django/django/pull/7777 is closed. Is it ok to get
correspondence for this because I would like to contribute?
--
Ticket URL: <https://code.djangoproject.com/ticket/27392#comment:19>
Django
Reporter: Tim Graham | Owner: Roman
Type: | Dmytriv
Cleanup/optimization | Status: assigned
Severity: Normal | Resolution:
Keywords: | Triage Stage: Accepted
Has patch: 0 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 1 | UI/UX: 0
Comment (by Tim Graham):
This is continued in [https://github.com/django/django/pull/8648 PR
#8648].
--
Ticket URL: <https://code.djangoproject.com/ticket/27392#comment:20>
Django
Reporter: Tim Graham | Owner: Roman
Type: | Dmytriv
Cleanup/optimization | Status: assigned
Severity: Normal | Resolution:
Keywords: | Triage Stage: Accepted
Has patch: 0 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 1 | UI/UX: 0
Comment (by Theofanis Despoudis):
Replying to [comment:20 Tim Graham]:
> This is continued in [https://github.com/django/django/pull/8648 PR
#8648].
Thank you, Tim.
Is it being worked on as it has been more than a month since the last
updates and more conflicts may appear?
--
Ticket URL: <https://code.djangoproject.com/ticket/27392#comment:21>
Django
-------------------------------------+-------------------------------------
Type: | Despoudis
Cleanup/optimization | Status: assigned
Component: Documentation | Version: master
Severity: Normal | Resolution:
Keywords: | Triage Stage: Accepted
Has patch: 0 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 1 | UI/UX: 0
-------------------------------------+-------------------------------------
* owner: Roman Dmytriv => Theofanis Despoudis
Comment:
Assigned to me as per
[https://github.com/django/django/pull/8648#issuecomment-315991751]
--
Ticket URL: <https://code.djangoproject.com/ticket/27392#comment:22>
Django
-------------------------------------+-------------------------------------
Reporter: Tim Graham | Owner: Theofanis
Type: | Despoudis
Cleanup/optimization | Status: assigned
Component: Documentation | Version: master
Severity: Normal | Resolution:
Keywords: | Triage Stage: Accepted
Has patch: 0 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 1 | UI/UX: 0
-------------------------------------+-------------------------------------
Comment (by Theofanis Despoudis):
While working on the issue I also notices there are more edge cases:
* Tests the
* Test If
* Test the
* Ensures
plus more variations of Prefixes
I/m using a slightly more informative grep search
grep -rInw "Test" *
That prints whole words and line numbers
I will work on it this weekend
--
Ticket URL: <https://code.djangoproject.com/ticket/27392#comment:23>
Django
Reporter: Tim Graham | Owner: za
Type: Cleanup/optimization | Status: assigned
Component: Documentation | Version: master
Severity: Normal | Resolution:
Keywords: | Triage Stage: Accepted
Has patch: 0 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 1 | UI/UX: 0
Changes (by za):
* owner: Theofanis Despoudis => za
Comment:
I'll try to work on this within this week.
--
Ticket URL: <https://code.djangoproject.com/ticket/27392#comment:24>
Django
Reporter: Tim Graham | Owner: Harshit
Type: | Agrawal
Cleanup/optimization | Status: assigned
Component: Documentation | Version: master
Severity: Normal | Resolution:
Keywords: | Triage Stage: Accepted
Has patch: 0 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 1 | UI/UX: 0
Changes (by Harshit Agrawal):
* owner: za => Harshit Agrawal
--
Ticket URL: <https://code.djangoproject.com/ticket/27392#comment:25>
Django
-------------------------------------+-------------------------------------
Reporter: Tim Graham | Owner: Harshit
Type: | Agrawal
Component: Documentation | Version: master
Severity: Normal | Resolution: wontfix
Keywords: | Triage Stage: Accepted
Has patch: 0 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 1 | UI/UX: 0
-------------------------------------+-------------------------------------
* status: assigned => closed
* resolution: => wontfix
Comment:
This ticket has too many poor attempts and is causing more distraction
than it's worth.
--
Ticket URL: <https://code.djangoproject.com/ticket/27392#comment:26>