[Python-Dev] doctest improvements

["Martin v. Löwis"]

Dave Harrison wrote:
> I'm interested in getting involved in python dev, how do you go about
> reviewing patches etc ?

Pick a patch that interests you, and that hasn't seen any comments
(if you run out of those, consider patches that have comments and
appear to have fizzled out). For these patches:
- check whether they are formally complete, i.e. whether they
   include test cases and documentation.
- check whether they actually work. Apply them, and run the
   test suite. At some point, run the entire Python test suite,
   to see whether they break anything else.
- if they are bug fixes, check whether they actually fix the
   bug they claim to fix (if they claim to fix bugs but don't
   actually state which bug they fix, make the submitter explain
   the problem first)
- if they add new features, determine:
   a) whether the feature could have negative effects on existing
      code, and
   b) whether the feature is desirable in your POV
- review the actual code:
   a) check whether it follows the style guide
   b) if it is C code, check for common mistakes, e.g. refcounting
      bugs
   c) check whether tricky aspects are properly commented
   d) check whether there are any border cases that would need
      consideration
When you have done your analysis, put your report as a comment
into the patch. This could be one of three outcomes:
a) the patch is acceptable
b) the patch should be rejected
c) the patch is acceptable in principle, and needs more work,
    or is just incomplete (so it needs more work but hasn't been
    fully reviewed)

For cases a) and b), if you have a list of five or so patches,
post them to python-dev, asking for somebody to commit the
a)-cases, and close the b)-cases as rejected.

For case c), see whether the author is willing to follow up.
If not, ping the author again after two months or so. If the
author is still not responsive, consider completing the patch
for yourself. If you find that the patch is not important
enough, consider rejection (I often do that, assuming that
somebody will do the work eventually if the feature is really
desired).

> I'm sure this question has been asked a million times before, but is
> there a list of things that need to be done ?

It's not that often asked as I'd like to, so I'm happy to answer it
every time it comes up. However, people have also added text to
the web pages summarizing these principles, at

http://www.python.org/dev/dev_intro.html

in the section "Helping out".

Regards,
Martin