[Python-Dev] checklist for filing a bug

[Terry Reedy]

"Raymond Hettinger" <python at rcn.com> wrote in message 
news:000f01c583ff$2a15d460$b432c797 at oemcomputer...
>> In order to lower the barrier for reporting bugs, writing patches, and
>> handling CVS commits, I am writing up checklists for each and I will
>> put them up on python.org.
>
> -0 on the checklists.

I am more enthusiastic about the idea of improving python.com's guidelines 
in this area, with some of Raymond's comments, and mine below, taken into 
consideration.  To start with, I think the Developers page should have Bug 
Submission Guidelines to go with the Patch Submission Guidelines.

Searching the site for 'bug reports' gives PEP 3 *Handling* (not 
submitting) Bug Reports as first hit.  It seems to have last been revised 
4-5 years ago.  Is there anything more recent I should be aware of?  PEP 3 
references Appendix B. Reporting Bugs of the current docs.  I believe this 
page could stand revision to be more list a checklist.

The search engine does *not* return this page (current App. B) among the 
first 10 of 19,000 (really?) reported hits.  I wish we could 'buy' words 
(for free) for searches on our own site or otherwise learn how to influence 
the search results.  The top 10 do include the appendix for earlier 
versions.  But this will won't help get people to the most recent version.

The search engine also reports Known Bugs lists such as 
http://www.python.org/2.4/bugs.html.
At the bottom is a very short blurb of how to report bugs, which does 
reference Appendix B (nor, of course, to your yet to be posted page).  The 
same applies to http://www.python.org/dev/tools.html.  I would really like 
to see one page, occasionally revised, that is referenced wherever the 
subject is discussed on the site.

Some specifics based on my experience reviewing bugs, mostly as 'triage 
nurse'.

I would like to see more emphasis that the Python SF bug list is for bugs 
in the PSF distribution, including documentation and std libs, which we can 
fix, and not for other stuff, including feature requests (see RFE tracker), 
non-bug change proposals (see PEPs), and bugs in 3rd party libraries and 
compilers (see their bug lists).

I would like it stated that a bug is generally a discrepancy between 
promise -- the documentaion-- and performance -- the implementation. 
(Non-documentation is another area.)  This means that 'reporting a bug' 
often means finding and reporting the section of the documentation -- the 
language or library reference -- that conflicts with the reported behavior. 
Many bugs reported today are not as obviously bugs as
>>> 2+2
5

I agree with Raymond that unittests are a nice optional extra but too much 
to expect.  You could mention that providing good, simple code 
demonstrating the bug, perhaps with multiple data inputs, makes it easier 
for the bug fixer to write a test so that the bug will be caught if 
reintroduced.

In summary, I think a good guideline page could improve reports and make 
first-reviews easier.

Terry J. Reedy