[Python-checkins] devguide: Add a doc outlining how to add something to the stdlib.

[brett.cannon]

brett.cannon pushed fd55b6d1d756 to devguide:

http://hg.python.org/devguide/rev/fd55b6d1d756
changeset:   97:fd55b6d1d756
tag:         tip
user:        Brett Cannon <brett at python.org>
date:        Sun Jan 16 12:38:37 2011 -0800
summary:
  Add a doc outlining how to add something to the stdlib.

files:
  index.rst
  stdlibchanges.rst

diff --git a/index.rst b/index.rst
--- a/index.rst
+++ b/index.rst
@@ -18,6 +18,8 @@
    coredev
    committing
 
+   stdlibchanges
+
 
 .. todolist::
 
@@ -55,10 +57,7 @@
 Proposing changes to Python itself
 ----------------------------------
 
-* `Changing something already in the stdlib <XXX>`_
-* Adding to the stdblib
-    * `Adding to a pre-existing module <XXX>`_
-    * `Adding a new module <XXX>`_
+* :ref:`stdlibchanges`
 * `Changing the language <XXX>`_
 
 
diff --git a/stdlibchanges.rst b/stdlibchanges.rst
new file mode 100644
--- /dev/null
+++ b/stdlibchanges.rst
@@ -0,0 +1,141 @@
+.. _stdlibchanges:
+
+Adding to the Stdlib
+====================
+
+While the stdlib contains a great amount of useful code, sometimes you want
+more than is provided. This document it meant to explain how you can get either
+a new addition to a pre-existing module in the stdlib or add an entirely new
+module.
+
+Changes to pre-existing code is not covered as that is considered a bugfix and
+thus is treated as a bug that should be filed on the `issue tracker`_.
+
+.. _issue tracker: http://bugs.python.org/
+
+
+Adding to a pre-existing module
+-------------------------------
+
+If you have found that a function, method, or class is useful and you believe
+it would be useful to the general Python community, there are some steps to go
+through in order to see it added to the stdlib.
+
+First is you need to gauge the usefulness of the code. Typically this is done
+by sharing the code publicly. You have a couple of options for this. One is to
+post it online at the `Python Cookbook`_. Based on feedback or reviews of the
+recipe you can see if others find the functionality as useful as you do.
+Another is to do a blog post about the code and see what kind of responses you
+receive. Posting to python-list (see :ref:`communication` for where to find the
+list and other mailing lists) to discuss your code also works. Finally, asking
+on a specific :abbr:`SIG (special interest group)` from mail.python.org or
+python-ideas is also acceptable.
+
+If you have found general acceptance and usefulness for your code from people,
+you can open an issue on the `issue tracker`_ with the code attached as a
+:ref:`patch <patch>`. If possible, also submit a
+:ref:`contributor agreement <contributor_agreement>`.
+
+If a core developer decides that your code would be useful to the general
+Python community, they will then commit your code. If your code is not picked
+up by a core developer and committed then please do not take this personally.
+Through your public sharing of your code in order to gauage community support
+for it you at least can know that others will come across it who may find it
+useful.
+
+.. _Python Cookbook: http://code.activestate.com/recipes/langs/python/
+
+
+Adding a new module
+-------------------
+It must be stated upfront that getting a new module into the stdlib is very
+difficult. Adding any significant amount of code to the stdlib increases the
+burden placed upon core developers. It also means that the module somewhat
+becomes "sanctioned" by the core developers as a good way to do something,
+typically leading to the rest of the Python community to using the new module
+over other available solutions. All of this means that additions to the stdlib
+are not taken lightly.
+
+
+Acceptable Types of Modules
+'''''''''''''''''''''''''''
+Typically two types of modules get added to the stdlib. One type is a module
+which implements something that is difficult to get right. A good example of
+this is the :py:mod:`multiprocessing` package. Working out the various OS
+issues, working through concurrency issues, etc. are all very difficult to get
+right.
+
+The second type of module is one that implements something that people
+re-implement constantly. The :py:mod:`itertools` module is a good example of
+this type as its constituent parts are not necessarily complex, but are used
+regularly in a wide range of programs and can be a little tricky to get right.
+Modules that parse widely used data formats also fall under this type of module
+that the stdlib consists of.
+
+While a new stdlib module does not need to appeal to all users of Python, it
+should be something that a large portion of the community will find useful.
+This makes sure that the developer burden placed upon core developers is worth
+it.
+
+
+Requirements
+''''''''''''''
+In order for a module to even be considered for inclusion into the stdlib, a
+couple requirements must be met. The most basic is that the code must meet the
+same requirements as that of any other :ref:`patch <patch>`. For code that has
+been developed outside the stdlib typically this means making sure the coding
+style guides are followed and that the proper tests have been written.
+
+The module needs to have been out in the community for at least a year. Because
+of Python's conservative nature when it comes to backwards-compatibility, when
+a module its API becomes frozen. This means that a module should only enter the
+stdlib when it is mature and gone through its "growing pains".
+
+The module needs to be consideredbest-of-breed. When something is included in
+the stdlib it tends to be chosen first for products over other third-party
+solutions. By virtue of having been available to the public for at least a
+year, a module needs to have established itself as (one of) the top choices by
+the community for solving the problem the module is intended for.
+
+The development of the module must move into Python's
+infrastructure (i.e., the module is no longer directly maintained outside of
+Python). This prevents a divergence between the code that is included in the
+stdlib and that which is released outside the stdlib (typically done to provide
+the module to older versions of Python). It also removes the burden of forcing
+core developers to have to redirect bug reports or patches to an external issue
+tracker and :abbr:`VCS (version control system)`.
+
+Someone involved with the development of the
+module must promise to help maintain the module in the stdlib for two years.
+This not only helps out other core developers by alleviating workload from bug
+reports that arrive from the first Python release containing the module, but
+also help make sure that the overall design of the module continues to be
+uniform.
+
+
+Proposal Process
+''''''''''''''''
+If the module you want to proposing adding to the stdlib meets the proper
+requirements, you may propose its inclusion. To start, you should email
+python-list or python-ideas to make sure the community in general would support
+the inclusion of the module (see :ref:`communication`).
+
+If the feedback from the community is positive overall, you will need to write
+a :abbr:`PEP (Python enhancement proposal)` for the module's inclusion. It
+should outline what the module's overall goal is, why it should be included in
+the stdlib, and specify the API of the module. See the `PEP index`_ for PEPs
+that have been accepted before that proposed a module for inclusion.
+
+Once your PEP is written, send it to python-ideas for basic vetting. Be
+prepared for extensive feedback and lots of discussion (not all of it
+positive). This will help make the PEP be of good quality and properly
+formatted.
+
+When you have listened to, responded, and integrated as appropriate the
+feedback from python-ideas into your PEP, you may send it to python-dev. You
+will once again receive a large amount of feedback and discussion. If the
+core developers end up agreeng in general to accepting your PEP then the module
+will be added to the stdlib once the creators of the module sign
+:ref:`contributor agreements <contributor_agreement>`.
+
+.. _PEP index: http://www.python.org/dev/peps/

--
Repository URL: http://hg.python.org/devguide