[Python-checkins] devguide (merge default -> default): merge

Fri Jan 25 20:13:54 CET 2013

http://hg.python.org/devguide/rev/1311495c7958
changeset: 595:1311495c7958
parent: 594:176190493186
parent: 593:139eea239f32
user: Brett Cannon <brett at python.org>
date: Fri Jan 25 14:13:48 2013 -0500
summary:
 merge
files:
 buildbots.rst | 2 +-
 committing.rst | 18 ++++-
 conf.py | 2 +-
 devcycle.rst | 9 ++-
 developers.rst | 3 +
 docquality.rst | 15 ++--
 documenting.rst | 47 ++++++++++-----
 experts.rst | 4 +-
 faq.rst | 6 ++
 index.rst | 105 +++++++++++++++++++++--------------
 langchanges.rst | 13 ++-
 patch.rst | 8 +-
 runtests.rst | 14 +++-
 setup.rst | 17 +++--
 tracker.rst | 6 +-
 triaging.rst | 10 ++-
 16 files changed, 181 insertions(+), 98 deletions(-)

diff --git a/buildbots.rst b/buildbots.rst
--- a/buildbots.rst
+++ b/buildbots.rst
@@ -54,7 +54,7 @@
 ---------
 
 A subset of the buildbots are marked "stable". They are taken into account
-when making a new release. The rule is that no stable buildbot must witness
+when making a new release. The rule is that all stable builders must be free of
 persistent failures when the release is cut. It is absolutely **vital**
 that core developers fix any issue they introduce on the stable buildbots,
 as soon as possible.
diff --git a/committing.rst b/committing.rst
--- a/committing.rst
+++ b/committing.rst
@@ -19,15 +19,15 @@
 Patch Checklist
 ---------------
 
-Here's the simple patch checklist that ``make patchcheck`` (or ``./python.exe
+Here's the simple patch checklist that ``make patchcheck`` (or ``./python.exe
 Tools/scripts/patchcheck.py`` on Windows) will run through
 on a system that uses the makefile to build Python:
 
 * Are there any whitespace problems in Python files?
- (using Tools/scripts/reindent.py)
+ (using ``Tools/scripts/reindent.py``)
 * Are there any whitespace problems in C files?
 * Are there any whitespace problems in the documentation?
- (using Tools/scripts/reindent-rst.py)
+ (using ``Tools/scripts/reindent-rst.py``)
 * Has the documentation been updated?
 * Has the test suite been updated?
 * Has ``Misc/NEWS`` been updated?
@@ -35,6 +35,7 @@
 * Has ``configure`` been regenerated, if necessary?
 * Has ``pyconfig.h.in`` been regenerated, if necessary?
 * Has the test suite been run?
+* Are there any reference leaks?
 
 Note that the automated patch check can't actually *answer* all of these
 questions, and even if it could, it still wouldn't know whether or not
@@ -306,17 +307,24 @@
 # Fix any conflicts; compile; run the test suite
 hg commit
 
+.. index:: null merging
+
 .. note::
- *If the patch shouldn't be ported* from Python 3.3 to Python 3.4, you must
- also make it explicit: merge the changes but revert them before committing::
+ If the patch should *not* be ported from Python 3.3 to Python 3.4, you must
+ also make this explicit by doing a *null merge*: merge the changes but
+ revert them before committing::
 
 hg update default
 hg merge 3.3
 hg revert -ar default
+ hg resolve -am # needed only if the merge created conflicts
 hg commit
 
 This is necessary so that the merge gets recorded; otherwise, somebody
 else will have to make a decision about your patch when they try to merge.
+ (Using a three-way merge tool generally makes the ``hg resolve`` step
+ in the above unnecessary; also see `this bug report
+ <http://bz.selenic.com/show_bug.cgi?id=2706>`__.)
 
 When you have finished your porting work (you can port several patches one
 after another in your local repository), you can push **all** outstanding
diff --git a/conf.py b/conf.py
--- a/conf.py
+++ b/conf.py
@@ -26,7 +26,7 @@
 # Add any Sphinx extension module names here, as strings. They can be extensions
 # coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
 extensions = ['sphinx.ext.intersphinx', 'sphinx.ext.todo']
-intersphinx_mapping = {'python': ('http://docs.python.org/py3k', None)}
+intersphinx_mapping = {'python': ('http://docs.python.org/3', None)}
 todo_include_todos = True
 
 # Add any paths that contain templates here, relative to this directory.
diff --git a/devcycle.rst b/devcycle.rst
--- a/devcycle.rst
+++ b/devcycle.rst
@@ -65,7 +65,8 @@
 --------------------
 
 A branch for a previous feature release, currently being maintained for bug
-fixes. There are currently two of them in activity: one for Python 3.x and
+fixes. There are usually two maintenance branches at any given time: one for
+Python 3.x and
 one for Python 2.x. At some point in the future, Python 2.x will be closed
 for bug fixes and there will be only one maintenance branch left.
 
@@ -75,8 +76,8 @@
 etc.). For both rules, only rare exceptions are accepted and **must** be
 discussed first.
 
-When a new maintenance branch is created (after a new *minor version* is
-released), the old maintenance branch on that major version (e.g. 3.2.x
+Sometime after a new maintenance branch is created (after a new *minor version*
+is released), the old maintenance branch on that major version (e.g. 3.2.x
 after 3.3 gets released) will go into :ref:`security mode <secbranch>`,
 usually after one last maintenance release at the discretion of the
 release manager.
@@ -96,6 +97,8 @@
 actual security patches have been applied to the branch.
 
 
+.. _listbranch:
+
 Summary
 -------
 
diff --git a/developers.rst b/developers.rst
--- a/developers.rst
+++ b/developers.rst
@@ -24,6 +24,9 @@
 Permissions History
 -------------------
 
+- Serhiy Storchaka was given push privileges on Dec 26 2012 by GFB, for general
+ contributions, on recommendation by Trent Nelson.
+
 - Chris Jerdonek was given push privileges on Sep 24 2012 by GFB, for general
 contributions, on recommendation by Ezio Melotti.
 
diff --git a/docquality.rst b/docquality.rst
--- a/docquality.rst
+++ b/docquality.rst
@@ -10,13 +10,14 @@
 
 :ref:`Documenting Python <documenting>` covers the details of how Python's documentation works.
 It includes an explanation of the markup used (although you can figure a lot
-out simply by looking at pre-existing documentation) and how to build the
-documentation (which allows you to see how your changes will look along with
-validating that your new markup is correct).
+out simply by looking at pre-existing documentation) and :ref:`how to build
+<building-doc>` the documentation (which allows you to see how your changes
+will look along with validating that your new markup is correct).
 
-The current in-development version of the documentation can be viewed at
-http://docs.python.org/dev/. This version is regenerated from source once
-a day.
+The documentation built from the :ref:`in-development <indevbranch>` and
+:ref:`maintenance <maintbranch>` branches can be viewed from
+http://docs.python.org/dev/. The in-development and most recent 2.x and 3.x
+maintenance :ref:`branches <listbranch>` are rebuilt once per day.
 
 If you would like a technical documentation style guide, the `Apple
 Publications Style Guide
@@ -73,7 +74,7 @@
 
 The Developer's Guide uses the same process as the main Python documentation,
 except for some small differences. The source lives in a `separate
-repository`_. Bug reports and and patches should be submitted to the `python
+repository`_. Bug reports and patches should be submitted to the `python
 bug tracker`_ using the ``devguide`` component. Changes to the devguide
 are normally published within a day, on a schedule that may be different from
 the main documentation.
diff --git a/documenting.rst b/documenting.rst
--- a/documenting.rst
+++ b/documenting.rst
@@ -1,5 +1,6 @@
 .. _documenting:
 
+==================
 Documenting Python
 ==================
 
@@ -17,8 +18,6 @@
 :ref:`CPython Mercurial repository <setup>`.
 
 .. _reStructuredText: http://docutils.sf.net/rst.html
-.. _docutils: http://docutils.sf.net/
-.. _Sphinx: http://sphinx.pocoo.org/
 
 .. note::
 
@@ -826,6 +825,17 @@
 This language is used until the next ``highlightlang`` directive is
 encountered.
 
+* The ``code-block`` directive can be used to specify the highlight language
+ of a single code block, e.g.::
+
+ .. code-block:: c
+
+ #include <stdio.h>
+
+ void main() {
+ printf("Hello world!\n");
+ }
+
 * The values normally used for the highlighting language are:
 
 * ``python`` (the default)
@@ -1628,28 +1638,30 @@
 Building the documentation
 ==========================
 
-You need to have Python 2.4 or higher installed; the toolset used to build the
-docs is written in Python. It is called *Sphinx*, it is not included in this
-tree, but maintained separately. Also needed are the docutils, supplying the
-base markup that Sphinx uses, Jinja, a templating engine, and optionally
-Pygments, a code highlighter.
+You need to have Python 2.4 or higher installed. The toolset used to build
+the docs is written in Python and is called Sphinx_. Sphinx is maintained
+separately and is not included in this tree. Also needed are docutils_,
+supplying the base markup that Sphinx uses; Jinja_, a templating engine; and
+optionally Pygments_, a code highlighter.
+
+To build the documentation, follow the instructions from one of the sections
+below. You can view the documentation after building the HTML by pointing
+a browser at the file :file:`Doc/build/html/index.html`.
 
 
 Using make
 ----------
 
-Luckily, a Makefile has been prepared so that on Unix, provided you have
-installed Python and Subversion, you can just go to your :ref:`clone of the
-CPython Mercurial repository <setup>` and run ::
+On Unix, if you have Subversion installed, run the following from the root of
+your :ref:`repository clone <checkout>`::
 
 cd Doc
 make html
 
-to check out the necessary toolset in the :file:`tools/` subdirectory and build
-the HTML output files. To view the generated HTML, point your favorite browser
-at the top-level index :file:`build/html/index.html` after running "make".
-
-Available make targets are:
+or alternatively ``make -C Doc html``. This checks out the needed toolset
+in the :file:`Doc/tools/` directory and builds the output as HTML.
+
+Available :command:`make` targets are:
 
 * "html", which builds standalone HTML files for offline viewing.
 
@@ -1719,3 +1731,8 @@
 
 where `<builder>` is one of html, text, latex, or htmlhelp (for explanations see
 the make targets above).
+
+.. _docutils: http://docutils.sourceforge.net/
+.. _Jinja: http://jinja.pocoo.org/
+.. _Pygments: http://pygments.org/
+.. _Sphinx: http://sphinx-doc.org/
diff --git a/experts.rst b/experts.rst
--- a/experts.rst
+++ b/experts.rst
@@ -140,7 +140,7 @@
 logging vinay.sajip
 lzma nadeem.vawda
 macpath
-mailbox
+mailbox petri.lehtinen
 mailcap
 marshal
 math mark.dickinson, rhettinger, stutzbach
@@ -167,7 +167,7 @@
 pkgutil
 platform lemburg
 plistlib
-poplib
+poplib giampaolo.rodola
 posix
 pprint fdrake
 profile georg.brandl
diff --git a/faq.rst b/faq.rst
--- a/faq.rst
+++ b/faq.rst
@@ -25,6 +25,10 @@
 .. _StackOverflow: http://stackoverflow.com/
 .. _Freenode: http://freenode.net/
 
+
+.. index::
+ single: PEP process; in FAQ
+
 .. _suggesting-changes:
 
 Where should I suggest new features and language changes?
@@ -48,6 +52,8 @@
 For some examples on language changes that were accepted please read
 `Justifying Python Language Changes`_.
 
+See also the :ref:`langchanges` section of this guide.
+
 .. _python-ideas: http://mail.python.org/mailman/listinfo/python-ideas
 .. _issue tracker: http://bugs.python.org
 .. _PEP Index: http://www.python.org/dev/peps
diff --git a/index.rst b/index.rst
--- a/index.rst
+++ b/index.rst
@@ -1,55 +1,38 @@
+========================
 Python Developer's Guide
 ========================
 
-.. toctree::
- :hidden:
-
- setup
- help
- patch
- runtests
- coverage
- docquality
- documenting
- silencewarnings
- fixingissues
- tracker
- triaging
- communication
- coredev
- developers
- committing
- devcycle
- buildbots
-
- stdlibchanges
- langchanges
-
- experts
- emacs
- gdb
- grammar
- compiler
- faq
+This guide is a comprehensive resource for :ref:`contributing <contributing>`
+to Python_ -- for both new and experienced contributors. It is
+:ref:`maintained <helping-with-the-developers-guide>` by the same community
+that maintains Python. We welcome your contributions to Python!
 
 
 Quick Start
 -----------
 
-Here is a list of the basic steps necessary to get set up and make a patch:
+Here are the basic steps needed to get :ref:`set up <setup>` and contribute a
+patch:
 
-1. Get :ref:`a clone of CPython <setup>` with ``hg clone
- http://hg.python.org/cpython``.
-2. On UNIX, run ``./configure --with-pydebug && make -j2`` to
- :ref:`build Python <compiling>`.
+1. :ref:`Get the source code <checkout>`::
 
- On :ref:`Windows <windows-compiling>`, load the project file
+ hg clone http://hg.python.org/cpython
+
+2. :ref:`Build Python <compiling>`. On :ref:`UNIX <unix-compiling>`::
+
+ ./configure --with-pydebug && make -j2
+
+ On :ref:`Windows <windows-compiling>`, open the solution file
 :file:`PCbuild\\pcbuild.sln` in Visual Studio, select :menuselection:`Debug`,
 and :menuselection:`Build --> Build Solution`.
-3. :doc:`Run the tests <runtests>` with ``./python -m test -j3`` (use
- :file:`./python.exe` on :ref:`most <python.exe>` Mac OS X systems and
- :file:`PCbuild\\python_d.exe` on Windows; replace ``test`` with
- ``test.regrtest`` for 2.7).
+3. :doc:`Run the tests <runtests>`::
+
+ ./python -m test -j3
+
+ On :ref:`most <mac-python.exe>` Mac OS X systems, replace :file:`./python`
+ with :file:`./python.exe`. On Windows, use :file:`PCbuild\\python_d.exe` or
+ check the :ref:`Windows instructions <win-python.exe>`. With Python 2.7,
+ replace ``test`` with ``test.regrtest``.
 4. Make the :doc:`patch <patch>`.
 5. Submit it to the `issue tracker`_.
 
@@ -66,6 +49,8 @@
 * PEPs_ (Python Enhancement Proposals)
 
 
+.. _contributing:
+
 Contributing
 ------------
 
@@ -122,6 +107,7 @@
 
 Also refer to :ref:`suggesting-changes` in the FAQ.
 
+
 Other Interpreter Implementations
 ---------------------------------
 
@@ -167,6 +153,7 @@
 * :doc:`faq`
 * :doc:`developers`
 
+
 Additional Resources
 --------------------
 
@@ -183,15 +170,51 @@
 
 * :ref:`Search this guide <search>`
 
+
+.. _contents:
+
+Full Table of Contents
+----------------------
+
+.. toctree::
+ :numbered:
+
+ setup
+ help
+ patch
+ runtests
+ coverage
+ docquality
+ documenting
+ silencewarnings
+ fixingissues
+ tracker
+ triaging
+ communication
+ coredev
+ developers
+ committing
+ devcycle
+ buildbots
+ stdlibchanges
+ langchanges
+ experts
+ emacs
+ gdb
+ grammar
+ compiler
+ faq
+
+
 .. _Buildbot status: http://python.org/dev/buildbot/
 .. _Firefox search engine plug-in: http://www.python.org/dev/searchplugin/
 .. _Misc directory: http://hg.python.org/cpython/file/default/Misc
 .. _PEPs: http://www.python.org/dev/peps
 .. _python.org maintenance: http://python.org/dev/pydotorg/
+.. _Python: http://www.python.org/
 .. _Python Mentors: http://pythonmentors.com/
 .. _PyPy: http://www.pypy.org/
 .. _Jython: http://www.jython.org/
 .. _IronPython: http://ironpython.net/
 .. _Stackless: http://www.stackless.com/
 .. _Issue tracker: http://bugs.python.org/
-
diff --git a/langchanges.rst b/langchanges.rst
--- a/langchanges.rst
+++ b/langchanges.rst
@@ -25,7 +25,7 @@
 is to ask on :ref:`python-list or python-ideas <communication>`. You can also
 go through Python's stdlib and find examples of code which would benefit from
 your proposed change (which helps communicate the usefulness of your change to
-others).
+others). For further guidance, see :ref:`suggesting-changes` in the FAQ.
 
 Your proposed change also needs to be *Pythonic*. While Guido is the only
 person who can truly classify something as Pythonic, you can read the `Zen of
@@ -34,11 +34,14 @@
 .. _Zen of Python: http://www.python.org/dev/peps/pep-0020/
 
 
-Process
--------
+.. index:: PEP process
+
+PEP Process
+-----------
 Once you are certain you have a language change proposal which will appeal to
-the general Python community, you can being the process of officially proposing
-the change.
+the general Python community, you can begin the process of officially proposing
+the change. This process is the Python Enhancement Proposal (PEP) process.
+:PEP:`1` describes it in detail.
 
 You will first need a PEP that you will present to python-ideas. You may be a
 little hazy on the technical details as various core developers can help with
diff --git a/patch.rst b/patch.rst
--- a/patch.rst
+++ b/patch.rst
@@ -139,9 +139,11 @@
 than there are people capable of reviewing your patch. Getting your patch
 reviewed requires a reviewer to have the spare time and motivation to
 look at your patch (we cannot force anyone to review patches). If your patch has
-not received any notice from reviewers (i.e., no comment made) after a
-substantial amount of time then you may
-email python-dev at python.org asking for someone to take a look at your patch.
+not received any notice from reviewers (i.e., no comment made) after one
+month, first "ping" the issue on the `issue tracker`_ to remind the nosy list
+that the patch needs a review. If you don't get a response within a few days
+after pinging the issue, then you can try emailing python-dev at python.org asking
+for someone to review your patch.
 
 When someone does manage to find the time to look at your patch they will most
 likely make comments about how it can be improved (don't worry, even core
diff --git a/runtests.rst b/runtests.rst
--- a/runtests.rst
+++ b/runtests.rst
@@ -18,10 +18,11 @@
 
 ./python -m test
 
-If you are using Python 2.7, then use the following instead as the basis
-for the commands in this section::
-
- ./python -m test.regrtest
+You may need to change this command as follows throughout this section.
+On :ref:`most <mac-python.exe>` Mac OS X systems, replace :file:`./python`
+with :file:`./python.exe`. On Windows, use :file:`PCbuild\\python_d.exe` or
+check the detailed :ref:`Windows instructions <win-python.exe>`. If using
+Python 2.7, replace ``test`` with ``test.regrtest``.
 
 If you don't have easy access to a command line, you can run the test suite from
 a Python or IDLE shell::
@@ -70,6 +71,11 @@
 The ``-uall`` flag allows the use of all available
 resources so as to not skip tests requiring, e.g., Internet access.
 
+To check for reference leaks (only needed if you modified C code), use the
+``-R`` flag. For example, ``-R 3:2`` will first run the test 3 times to settle
+down the reference count, and then run it 2 more times to verify if there are
+any leaks.
+
 You can also execute the ``Tools/scripts/run_tests.py`` script as found in a
 CPython checkout. The script tries to balance speed with thoroughness. But if
 you want the most thorough tests you should use the strenuous approach shown
diff --git a/setup.rst b/setup.rst
--- a/setup.rst
+++ b/setup.rst
@@ -1,15 +1,16 @@
-.. _setup:
-
-Getting Set Up
-==============
+===============
+Getting Started
+===============
 
 These instructions cover how to get a working copy of the source code and a
 compiled version of the CPython interpreter (CPython is the version of Python
 available from http://www.python.org/). It also gives an overview of the
 directory structure of the CPython source code.
 
-.. contents::
+.. _setup:
 
+Getting Set Up
+==============
 
 Version Control Setup
 ---------------------
@@ -121,6 +122,8 @@
 more Python code than C.
 
 
+.. _unix-compiling:
+
 UNIX
 ''''
 
@@ -150,7 +153,7 @@
 Otherwise the build failed and thus should be fixed (at least with a bug being
 filed on the `issue tracker`_).
 
-.. _python.exe:
+.. _mac-python.exe:
 
 Once CPython is done building you will then have a working build
 that can be run in-place; ``./python`` on most machines (and what is used in
@@ -216,6 +219,8 @@
 Visual Studio, or choosing Start Debugging from the Debug menu, will launch
 the interpreter.
 
+.. _win-python.exe:
+
 If you want to launch the compiled interpreter from the command-line, the
 path varies according to the build. For a 32-bit build in debug mode, you
 have to invoke ``PCBuild\python_d.exe``, for a 64-bit build in debug mode,
diff --git a/tracker.rst b/tracker.rst
--- a/tracker.rst
+++ b/tracker.rst
@@ -1,3 +1,7 @@
+==============
+Issue Tracking
+==============
+
 .. _tracker:
 
 Using the Issue Tracker
@@ -46,7 +50,7 @@
 * if you have JavaScript enabled, you can use the **Nosy List** field to search
 developers that can help with the issue by entering the name of the affected
 module, operating system, or interest area.
-* least but not last, you have to describe the problem in detail, including
+* last but not least, you have to describe the problem in detail, including
 what you expected to happen and what did happen, in the **Comment** field.
 Be sure to include whether any extension modules were involved, and what
 hardware and software platform you were using (including version information
diff --git a/triaging.rst b/triaging.rst
--- a/triaging.rst
+++ b/triaging.rst
@@ -256,11 +256,12 @@
 Mercurial Repository
 ''''''''''''''''''''
 HTTP link to a Mercurial repository that contains a patch for the issue.
-The `Create Patch` button will then compute a diff for the head revision
-of the remote branch, and attach the diff to the issue.
+A :guilabel:`Create Patch` button will appear that computes a diff for the
+head revision of the remote branch and attaches it to the issue. The button
+supports only CPython_ patches.
 
-If you don't indicate a remote branch, ``default`` is used. You can
-indicate a remote branch adding ``#BRANCH`` at the end of the URL.
+If you don't indicate a remote branch, ``default`` is used. You can
+indicate a remote branch by adding ``#BRANCH`` to the end of the URL.
 
 Generating Special Links in a Comment
 -------------------------------------
@@ -290,6 +291,7 @@
 the Devguide, this page, and this section respectively.
 
 
+.. _CPython: http://hg.python.org/cpython/file/default/
 .. _Doc: http://hg.python.org/cpython/file/default/Doc/
 .. _Grammar: http://hg.python.org/cpython/file/default/Grammar/
 .. _Lib: http://hg.python.org/cpython/file/default/Lib/
-- 
Repository URL: http://hg.python.org/devguide
