Merge from upstream CPython devguide

Conflicts resolved manually in  documenting.rst, index.rst and
pullrequest.rst

Author: jeff5

.github/CODE_OF_CONDUCT.rst

@@ -0,0 +1,15 @@
+:orphan:
+
+Code of Conduct
+===============
+
+Please note that all interactions on
+`Python Software Foundation <https://www.python.org/psf-landing/>`__-supported
+infrastructure is `covered
+<https://www.python.org/psf/records/board/minutes/2014-01-06/#management-of-the-psfs-web-properties>`__
+by the `PSF Code of Conduct <https://www.python.org/psf/codeofconduct/>`__,
+which includes all infrastructure used in the development of Python itself
+(e.g. mailing lists, issue trackers, GitHub, etc.).
+
+In general this means everyone is expected to be open, considerate, and
+respectful of others no matter what their position is within the project.

buildbots.rst

@@ -4,8 +4,8 @@ Continuous Integration
 ======================
 
 To assert that there are no regressions in the :doc:`development and maintenance
-branches <devcycle>`, Python has a set of dedicated machines (called *buildbots* or
-*build slaves*) used for continuous integration.  They span a number of
+branches <devcycle>`, Python has a set of dedicated machines (called *buildbots*
+or *build slaves*) used for continuous integration.  They span a number of
 hardware/operating system combinations.  Furthermore, each machine hosts
 several *builders*, one per active branch: when a new change is pushed
 to this branch on the public Mercurial repository, all corresponding builders
@@ -38,7 +38,7 @@ There are three ways of visualizing recent build results:
   https://code.google.com/archive/p/bbreport. Installing it is trivial: just add
   the directory containing ``bbreport.py`` to your system path so that
   you can run it from any filesystem location.  For example, if you want
-  to display the latest build results on the development ("default") branch,
+  to display the latest build results on the development ("master") branch,
   type::
 
       bbreport.py -q 3.x
@@ -186,8 +186,8 @@ offenders:
 When you think a failure might be transient, it is recommended you confirm by
 waiting for the next build.  Still, even if the failure does turn out sporadic
 and unpredictable, the issue should be reported on the bug tracker; even
-better if it can be diagnosed and suppressed by fixing the test's implementation,
-or by making its parameters - such as a timeout - more robust.
+better if it can be diagnosed and suppressed by fixing the test's
+implementation, or by making its parameters - such as a timeout - more robust.
 
 
 Custom builders

committing.rst

@@ -64,54 +64,8 @@ passes before merging any code changes.
 Patch checklist
 '''''''''''''''
 
-Along with running the tests, a simple automated patch checklist, ``patchcheck``,
-guides a developer through the common patch generation checks. To run
-``patchcheck``:
-
-   On *UNIX* (including Mac OS X)::
-
-      make patchcheck
-
-   On *Windows* (after any successful build)::
-
-      python.bat Tools/scripts/patchcheck.py
-
-The automated patch checklist runs through:
-
-* Are there any whitespace problems in Python files?
-  (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``)
-* Has the documentation been updated?
-* Has the test suite been updated?
-* Has an entry under ``Misc/NEWS.d/next`` been added?
-* Has ``Misc/ACKS`` been updated?
-* Has ``configure`` been regenerated, if necessary?
-* Has ``pyconfig.h.in`` been regenerated, if necessary?
-
-The automated patch check doesn't actually *answer* all of these
-questions. Aside from the whitespace checks, the tool is
-a memory aid for the various elements that can go into
-making a complete patch.
-
-
-Commit Style
-------------
-
-.. move this to pullrequest
-
-Once a change patch is ready and tested, it can be committed to the repository.
-We usually prefer to put a whole feature or bugfix into a single commit, but no
-more.  In particular:
-
-* Do **not** fix more than one issue in the same commit (except, of course, if
-  one code change fixes all of them).
-* Do **not** do cosmetic changes to unrelated code in the same commit as some
-  feature/bugfix.
-
-It is of course okay to pile up several commits to one branch and merge them
-into another in one commit.
+You should also :ref:`run patchcheck <patchcheck>` to perform a quick
+sanity check on the changes.
 
 
 Handling Others' Code
@@ -245,39 +199,8 @@ allowed here because news entries are meant to be as readable as possible
 unprocessed.)
 
 
-Commit Messages
----------------
-
-.. move to pullrequest
-
-Every commit has a commit message to document why a change was made and to
-communicate that reason to other core developers. Python core developers have
-developed a standard way of formatting commit messages that everyone is
-expected to follow.
-
-Our usual convention mimics that used in news entries (it is actually common to
-start by pasting the news entry into the commit message). The only key
-difference when compared to a news entry is the inclusion of the issue number
-as the beginning of the commit message. Here is an example::
-
-   bpo-42: the spam module is now more spammy.
-
-   The spam module sporadically came up short on spam. This change
-   raises the amount of spam in the module by making it more spammy.
-
-   Thanks to Monty Python for the patch.
-
-The first line or sentence is meant to be a dense, to-the-point explanation
-of what the purpose of the commit is.  If this is not enough detail for a commit,
-a new paragraph(s) can be added to explain in proper depth what has happened
-(detail should be good enough that a core developer reading the commit message
-understands the justification for the change).  Also, if a non-core developer
-contributed to the resolution, it is good practice to credit them.
-
-
-
 Working with Git_
-=================
+-----------------
 
 .. seealso::
    :ref:`gitbootcamp`
@@ -291,13 +214,17 @@ repositories means you have to be more careful with your workflow:
   dedicated to maintenance of the work before the work gets integrated in the
   main repository.
 
+  An exception to this rule: you can make a quick edit through the web UI of
+  GitHub, in which case the branch you create can exist for less than 24 hours.
+  This exception should not be abused and be left only for very simple changes.
+
 * You should not commit directly into the ``master`` branch, or any of the
-  maintenance branches (``2.7``, ``3.5``, or ``3.6``).  You should commit against
-  your own feature branch, and create a pull request.
+  maintenance branches (currently ``2.7`` or ``3.6``).
+  You should commit against your own feature branch, and create a pull request.
 
-It is recommended to keep a fork of the main repository around, as it allows simple
-reversion of all local changes (even "committed" ones) if your local clone gets
-into a state you aren't happy with.
+It is recommended to keep a fork of the main repository around, as it allows
+simple reversion of all local changes (even "committed" ones) if your local
+clone gets into a state you aren't happy with.
 
 
 .. _Git: https://git-scm.com/
@@ -306,7 +233,7 @@ into a state you aren't happy with.
 .. _committing-active-branches:
 
 Active branches
----------------
+'''''''''''''''
 
 If you do ``git branch`` you will see a :ref:`list of branches <listbranch>`.
 ``master`` is the in-development branch, and is the only branch that receives
@@ -316,17 +243,19 @@ new features.  The other branches only receive bug fixes or security fixes.
 .. _branch-merge:
 
 Backporting Changes to an Older Version
----------------------------------------
+'''''''''''''''''''''''''''''''''''''''
 
-When it is determined that a pull request needs to be backported into one or more of
-the maintenance branches, a core developer can apply the labels ``needs backport to X.Y``
-to the pull request.
+When it is determined that a pull request needs to be backported into one or
+more of the maintenance branches, a core developer can apply the labels
+``needs backport to X.Y`` to the pull request.
 
-After the pull request has been merged, it can be backported using cherry_picker.py_.
+After the pull request has been merged, it can be backported using
+cherry_picker.py_.
 
-The commit hash can be obtained from the original pull request, or by using `git log`
-on the ``master`` branch.  To display the 10 most recent commit hashes and their first
-line of the commit message::
+The commit hash can be obtained from the original pull request, or by using
+``git log`` on the ``master`` branch.
+To display the 10 most recent commit hashes and their first line of the commit
+message::
 
    git log -10 --oneline
 
@@ -344,7 +273,7 @@ Developers can apply labels to GitHub pull requests).
 
 
 Reverting a Merged Pull Request
--------------------------------
+'''''''''''''''''''''''''''''''
 
 To revert a merged pull request, press the ``Revert`` button at the bottom of
 the pull request.  It will bring up the page to create a new pull request where

communication.rst

@@ -49,10 +49,10 @@ Python-ideas_ is a mailing list open to the public to discuss ideas on changing
 Python. If a new idea does not start here (or python-list_, discussed below),
 it will get redirected here.
 
-Sometimes people post new ideas to python-list_ to gather community opinion before
-heading to python-ideas_. The list is also sometimes known as comp.lang.python,
-the name of the newsgroup it mirrors (it is also known by the abbreviation
-c.l.py).
+Sometimes people post new ideas to python-list_ to gather community opinion
+before heading to python-ideas_. The list is also sometimes known as
+comp.lang.python, the name of the newsgroup it mirrors (it is also known by
+the abbreviation c.l.py).
 
 The python-committers_ mailing list is a private mailing list for core
 developers (the archives are publicly available).

compiler.rst

@@ -97,14 +97,14 @@ approach and syntax::
   {
         stmt = FunctionDef(identifier name, arguments args, stmt* body,
                             expr* decorators)
-              | Return(expr? value) | Yield(expr value)
+              | Return(expr? value) | Yield(expr? value)
               attributes (int lineno)
   }
 
-The preceding example describes three different kinds of statements;
-function definitions, return statements, and yield statements.  All
-three kinds are considered of type ``stmt`` as shown by ``|`` separating the
-various kinds.  They all take arguments of various kinds and amounts.
+The preceding example describes two different kinds of statements and an
+expression: function definitions, return statements, and yield expressions.
+All three kinds are considered of type ``stmt`` as shown by ``|`` separating
+the various kinds.  They all take arguments of various kinds and amounts.
 
 Modifiers on the argument type specify the number of values needed; ``?``
 means it is optional, ``*`` means 0 or more, while no modifier means only one
@@ -170,11 +170,11 @@ very beginning of the compiler or the end, you need to care about how the arena
 works.  All code relating to the arena is in either :file:`Include/pyarena.h` or
 :file:`Python/pyarena.c`.
 
-``PyArena_New()`` will create a new arena.  The returned ``PyArena`` structure will
-store pointers to all memory given to it.  This does the bookkeeping of what
-memory needs to be freed when the compiler is finished with the memory it used.
-That freeing is done with ``PyArena_Free()``.  This only needs to be called in
-strategic areas where the compiler exits.
+``PyArena_New()`` will create a new arena.  The returned ``PyArena`` structure
+will store pointers to all memory given to it.  This does the bookkeeping of
+what memory needs to be freed when the compiler is finished with the memory it
+used. That freeing is done with ``PyArena_Free()``.  This only needs to be
+called in strategic areas where the compiler exits.
 
 As stated above, in general you should not have to worry about memory
 management when working on the compiler.  The technical details have been
@@ -367,23 +367,24 @@ bytecode step of the compiler.  Several pieces of code throughout Python depend
 on having correct information about what bytecode exists.
 
 First, you must choose a name and a unique identifier number.  The official
-list of bytecode can be found in :file:`Include/opcode.h`.  If the opcode is to take
-an argument, it must be given a unique number greater than that assigned to
+list of bytecode can be found in :file:`Include/opcode.h`.  If the opcode is to
+take an argument, it must be given a unique number greater than that assigned to
 ``HAVE_ARGUMENT`` (as found in :file:`Include/opcode.h`).
 
 Once the name/number pair has been chosen and entered in Include/opcode.h,
 you must also enter it into :file:`Lib/opcode.py` and
 :file:`Doc/library/dis.rst`.
 
 With a new bytecode you must also change what is called the magic number for
-.pyc files.  The variable ``MAGIC`` in :file:`Python/import.c` contains the number.
+.pyc files.  The variable ``MAGIC`` in :file:`Python/import.c` contains the
+number.
 Changing this number will lead to all .pyc files with the old ``MAGIC``
 to be recompiled by the interpreter on import.
 
 Finally, you need to introduce the use of the new bytecode.  Altering
 :file:`Python/compile.c` and :file:`Python/ceval.c` will be the primary places
-to change. But you will also need to change the 'compiler' package.  The key files
-to do that are :file:`Lib/compiler/pyassem.py` and
+to change. But you will also need to change the 'compiler' package.
+The key files to do that are :file:`Lib/compiler/pyassem.py` and
 :file:`Lib/compiler/pycodegen.py`.
 
 If you make a change here that can affect the output of bytecode that
@@ -392,10 +393,10 @@ sure to delete your old .py(c|o) files!  Even though you will end up changing
 the magic number if you change the bytecode, while you are debugging your work
 you will be changing the bytecode output without constantly bumping up the
 magic number.  This means you end up with stale .pyc files that will not be
-recreated.  Running
-``find . -name '*.py[co]' -exec rm -f {} ';'`` should delete all .pyc files you
-have, forcing new ones to be created and thus allow you test out your new
-bytecode properly.
+recreated.
+Running ``find . -name '*.py[co]' -exec rm -f {} ';'`` should delete all .pyc
+files you have, forcing new ones to be created and thus allow you test out your
+new bytecode properly.
 
 
 Code Objects

devcycle.rst

@@ -58,7 +58,7 @@ It is the branch :ref:`checked out <checkout-jy>` by default by Mercurial.
 
 At some point during the life-cycle of a release, a
 new :ref:`maintenance branch <maintbranch>` is created to host all bug fixing
-activity for further micro versions in a feature version (3.3.1, 3.3.2, etc.).
+activity for further micro versions in a feature version (3.6.1, 3.6.2, etc.).
 
 For versions 3.4 and before, this was conventionally done when the final
 release was cut (for example, 3.4.0 final).
@@ -122,7 +122,7 @@ security patches have been applied to the branch.
 Summary
 -------
 
-There are 6 open branches right now in the Git repository:
+There are 5 open branches right now in the Git repository:
 
 .. warning:: CPython-specific
 
@@ -134,8 +134,6 @@ There are 6 open branches right now in the Git repository:
   (RM: Larry Hastings)
 - the ``3.4`` branch accepts security fixes for future 3.4.x security releases
   (RM: Larry Hastings)
-- the ``3.3`` branch accepts security fixes for future 3.3.x security releases
-  (RM: Georg Brandl) [end-of-life for 3.3 is 2017-09-29]
 - the ``2.7`` branch accepts bug fixes for future 2.7.x maintenance releases
   (RM: Benjamin Peterson)
 
@@ -186,11 +184,11 @@ bug fixes can now be committed.  This is when core developers should concentrate
 on the task of fixing regressions and other new issues filed by users who have
 downloaded the alpha and beta releases.
 
-Being in beta can be viewed much like being in RC_ but without the extra overhead
-of needing commit reviews.
+Being in beta can be viewed much like being in RC_ but without the extra
+overhead of needing commit reviews.
 
-Please see the note in the `In-development (main) branch`_ section above
-for new information about the creation of the 3.5 maintenance branch during beta.
+Please see the note in the `In-development (main) branch`_ section above for
+new information about the creation of the 3.5 maintenance branch during beta.
 
 
 .. _rc:
@@ -201,8 +199,8 @@ Release Candidate (RC)
 A branch preparing for an RC release can only have bugfixes applied that have
 been reviewed by other core developers.  Generally, these issues must be
 severe enough (e.g. crashes) that they deserve fixing before the final release.
-All other issues should be deferred to the next development cycle, since stability
-is the strongest concern at this point.
+All other issues should be deferred to the next development cycle, since
+stability is the strongest concern at this point.
 
 You **cannot** skip the peer review during an RC, no matter how small! Even if
 it is a simple copy-and-paste change, **everything** requires peer review from

developers.rst

@@ -14,9 +14,9 @@ change or granted access.  The procedure for adding or removing users is
 described in :ref:`altering-access`.
 
 Note, when giving new commit permissions, be sure to get a contributor agreement
-from the committer.  See https://www.python.org/psf/contrib/ for details.  Commit
-privileges should not be given until the contributor agreement has been signed
-and received.
+from the committer.  See https://www.python.org/psf/contrib/ for details.
+Commit privileges should not be given until the contributor agreement has been
+signed and received.
 
 This file is encoded in UTF-8.  If the usual form for a name is not in
 a Latin or extended Latin alphabet, make sure to include an ASCII
@@ -105,6 +105,9 @@ Permissions History
 - Eric Snow was given push privileges on Sep 5 2012 by Antoine Pitrou for
   general contributions, on recommendation by Nick Coghlan.
 
+- Jeff Allen was given push privileges on June 13, 2012 by Antoine Pitrou,
+  at the request of Frank Wierzbicki, for Jython development.
+
 - Peter Moody was given push privileges on May 20 2012 by Antoine Pitrou for
   authorship and maintenance of the ipaddress module (accepted in PEP 3144 by
   Nick Coghlan).