[Python-Dev] Convention on functions that shadow existing stdlib functions

[Nick Coghlan]

On Sat, Jul 30, 2011 at 1:18 AM, Barry Warsaw <barry at python.org> wrote:
> On Jul 29, 2011, at 02:07 PM, Eli Bendersky wrote:
>>I think the unlink&rmtree functions are just a symptom. The real issue here
>>is - what is the devguide for, and how is it different from Python's
>>existing documentation? What should go into the official docs, and what
>>should go into the devguide? Once we agree on these question, I think the
>>test.support dilemma will solve itself.
>
> Let's see!
>
> I think the devguide should document things like "how to submit bugs", "how to
> use Mercurial", "how to propose changes to Python", "how to ensure code works
> across all existing interpreter implementations", "where to find continuous
> integration results and how to interpret them", "what's the right forum to
> discuss Python", etc.  I.e. processes, workflows, and conventions that are
> important cultural artifacts we've built up over 20 years.
>
> I don't think the devguide should document the actual code we ship.

I think everything related to *changing* Python should be in the
devguide, not the standard library docs. So the documentation on how
to *run* the test suite belongs in the devguide, but the details of
how the test suite works internally, including the APIs that are used
to write new tests, belong in the dev guide.

Now, perhaps a copy of the dev guide should be bundled with all future
releases rather than relying on the availability of a net connection
to access wart, but finally getting rid of the dodgy test.support
sort-of-docs out of the standard library docs is an excellent change.

As far as improving the arrangement goes, the checkin privileges are
the same as those for the main source tree - patches welcome :)

Cheers,
Nick.

-- 
Nick Coghlan   |   ncoghlan at gmail.com   |   Brisbane, Australia