[Python-checkins] devguide (merge default -> default): merge heads
benjamin.peterson
python-checkins at python.org
Tue Jun 28 00:54:43 CEST 2011
http://hg.python.org/devguide/rev/54f788c62ef5
changeset: 437:54f788c62ef5
parent: 436:607970c2b24b
parent: 435:63f3521fe8f8
user: Benjamin Peterson <benjamin at python.org>
date: Mon Jun 27 17:54:43 2011 -0500
summary:
merge heads
files:
committing.rst | 104 +++++++++++++++++++++++++++++++++---
docquality.rst | 10 +++
experts.rst | 1 +
faq.rst | 102 +++++++++++++++++++++++++++++++++++-
help.rst | 58 +++++++++++++++----
index.rst | 64 ++++++++++++++++++---
patch.rst | 4 +-
7 files changed, 304 insertions(+), 39 deletions(-)
diff --git a/committing.rst b/committing.rst
--- a/committing.rst
+++ b/committing.rst
@@ -3,8 +3,29 @@
Committing and Pushing Changes
==============================
-.. TODO: include a checklist of items to be included in a commit?
- e.g updated Misc/NEWS entry, tests, doc
+Patch Checklist
+---------------
+
+Here's the simple patch checklist that ``make patchcheck`` 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)
+* 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 ``Misc/NEWS`` been updated?
+* Has ``Misc/ACKS`` been updated?
+* Has the test suite been run?
+
+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
+those answers were appropriate. Aside from the whitespace checks, it is just
+a memory aid to help with remembering the various elements that can go into
+making a complete patch.
+
Commit Messages
---------------
@@ -54,6 +75,10 @@
such as mq_ (Mercurial Queues), in order to maintain patches in a single
local repository and to push them seamlessly when they are ready.
+It can also be useful to keep a pristine clone 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.
+
.. _Mercurial: http://www.hg-scm.org/
.. _mq: http://mercurial.selenic.com/wiki/MqExtension
@@ -119,6 +144,41 @@
**will** break someone's code). If you are unsure if the breakage is worth it,
ask on python-dev.
+Third, ensure the patch is attributed correctly by adding the contributor's
+name to ``Misc/ACKS`` if they aren't already there (and didn't add themselves
+in their patch) and by mentioning "Patch by <x>" in the ``Misc/NEWS`` entry
+and the checkin message. If the patch has been heavily modified then "Initial
+patch by <x>" is an appropriate alternate wording.
+
+If you omit correct attribution in the initial checkin, then update ``ACKS``
+and ``NEWS`` in a subsequent checkin (don't worry about trying to fix the
+original checkin message in that case).
+
+
+Contributor Licensing Agreements
+--------------------------------
+
+It's unlikely bug fixes will require a `Contributor Licensing Agreement`_
+unless they touch a *lot* of code. For new features, it is preferable to
+ask that the contributor submit a signed CLA to the PSF as the associated
+comments, docstrings and documentation are far more likely to reach a
+copyrightable standard.
+
+For Python sprints we now recommend collecting CLAs as a matter of course, as
+the folks leading the sprints can then handle the task of scanning (or otherwise
+digitising) the forms and passing them on to the PSF secretary. (Yes, we
+realise this process is quite archaic. Yes, we're in the process of fixing
+it. No, it's not fixed yet).
+
+As discussed on the PSF Contribution_ page, it is the CLA itself that gives
+the PSF the necessary relicensing rights to redistribute contributions under
+the Python license stack. This is an additional permission granted above and
+beyond the normal permissions provided by the chosen open source license.
+
+.. _Contribution: http://www.python.org/psf/contrib/
+.. _Contributor Licensing Agreement:
+ http://www.python.org/psf/contrib/contrib-form/
+
Forward-Porting
---------------
@@ -135,7 +195,7 @@
Even when porting an already committed patch, you should **still** check the
test suite runs successfully before committing the patch to another branch.
Subtle differences between two branches sometimes make a patch bogus if
- ported straightly.
+ ported without any modifications.
Porting Within a Major Version
@@ -222,8 +282,8 @@
There are various ways to achieve this, but here is a possible scenario:
-* First do a clone of the public repository, whose working copy will be updated
- to the ``default`` branch::
+* First do a clone of the public repository, whose working copy will be
+ updated to the ``default`` branch::
$ hg clone ssh://hg@hg.python.org/cpython py3k
@@ -234,10 +294,11 @@
$ cd py3.2
$ hg update 3.2
-* If you also need the 3.1 branch, you can similarly clone it, either from
- the ``py3.2`` or the ``py3k`` repository. It is suggested, though, that you
- clone from ``py3.2`` as that it will force you to push changes back up your
- clone chain so that you make sure to port changes to all proper versions.
+* If you also need the 3.1 branch to work on security fixes, you can similarly
+ clone it, either from the ``py3.2`` or the ``py3k`` repository. It is
+ suggested, though, that you clone from ``py3.2`` as that it will force you
+ to push changes back up your clone chain so that you make sure to port
+ changes to all proper versions.
* You can also clone a 2.7-dedicated repository from the ``py3k`` branch::
@@ -253,8 +314,25 @@
from the ``py3k`` repository will publish your changes in the public
repository.
+When working with this kind of arrangement, it can be useful to have a simple
+script that runs the necessary commands to update all branches with upstream
+changes::
+
+ cd ~/py3k
+ hg pull -u
+ cd ~/py3.2
+ hg pull -u
+ cd ~/py2.7
+ hg pull -u
+
+Only the first of those updates will touch the network - the latter two will
+just transfer the changes locally between the relevant repositories.
+
If you want, you can later :ref:`change the flow of changes <hg-paths>` implied
-by the cloning of repositories.
+by the cloning of repositories. For example, you may choose to add a separate
+``sandbox`` repository for experimental code (potentially published somewhere
+other than python.org) or an additional pristine repository that is
+never modified locally.
Differences with ``svnmerge``
@@ -354,8 +432,14 @@
mywork
$ hg merge default
+Rather than using a clone on ``python.org`` (which isn't particularly useful
+for collaboration with folks that don't already have CPython commit rights),
+Bitbucket_ also maintain an `up to date clone`_ of the main ``cpython``
+repository that can be used as the basis for a new clone or patch queue.
.. _named branch: http://mercurial.selenic.com/wiki/NamedBranches
+.. _Bitbucket: http://www.bitbucket.org
+.. _up to date clone: https://bitbucket.org/mirror/cpython/overview
Uploading a patch for review
diff --git a/docquality.rst b/docquality.rst
--- a/docquality.rst
+++ b/docquality.rst
@@ -66,3 +66,13 @@
to finish, filing issues in the issue tracker for each problem you find. Don't
file a single issue for an entire section containing multiple problems as that
makes it harder to break the work up for multiple people to help with.
+
+
+Helping with the Developer's Guide
+----------------------------------
+
+This developer guide lives in a `separate source code repository`_, but is
+otherwise managed using the same process as is used for the main Python
+documentation.
+
+.. _separate source code repository: http://hg.python.org/devguide
diff --git a/experts.rst b/experts.rst
--- a/experts.rst
+++ b/experts.rst
@@ -299,6 +299,7 @@
context managers ncoghlan
data formats mark.dickinson, georg.brandl
database lemburg
+devguide ncoghlan, eric.araujo
documentation georg.brandl, ezio.melotti, eric.araujo
GUI
i18n lemburg, eric.araujo
diff --git a/faq.rst b/faq.rst
--- a/faq.rst
+++ b/faq.rst
@@ -8,8 +8,108 @@
.. contents::
:local:
+
+Communications
+==============
+
+
+Where should I ask general Python questions?
+--------------------------------------------
+
+General Python questions should still go to `python-list`_ or `python-tutor`_
+or similar resources, such as StackOverflow_ or ``#python`` on IRC.
+
+.. _python-list: http://mail.python.org/mailman/listinfo/python-list
+.. _python-tutor: http://mail.python.org/mailman/listinfo/python-tutor
+.. _StackOverflow: http://stackoverflow.com/
+
+
+Where should I suggest new features and language changes?
+---------------------------------------------------------
+
+The `python-ideas`_ mailing list is specifically intended for discussion of
+new features and language changes. Please don't be disappointed if your
+idea isn't met with universal approval: as the long list of Rejected and
+Withdrawn PEPs in the `PEP Index`_ attests, and as befits a reasonably mature
+programming language, getting significant changes into Python isn't a simple
+task.
+
+If the idea is reasonable, someone will suggest posting it as a feature
+request on the `issue tracker`_.
+
+.. _python-ideas: http://mail.python.org/mailman/listinfo/python-ideas
+.. _issue tracker: http://bugs.python.org
+.. _PEP Index: http://www.python.org/dev/peps
+
+
+Where should I ask general questions about contributing to CPython?
+-------------------------------------------------------------------
+
+The `Python Mentors`_ program is specifically about encouraging
+developers and others that would like to contribute to Python development in
+general, rather than necessarily being focused on one particular issue.
+
+.. _Python Mentors: http://pythonmentors.com
+
+
+Where should I report specific problems?
+----------------------------------------
+
+Specific problems should be posted to the `issue tracker`_.
+
+
+What if I'm not sure it is a bug?
+---------------------------------
+
+The general Python help locations listed above are the best place to start
+with that kind of question. If they agree it looks like a bug, then the
+next step is to either post it to the `issue tracker`_ or else to ask further
+on the core development mailing list, `python-dev`_.
+
+.. _python-dev: http://mail.python.org/mailman/listinfo/python-dev
+
+
+What if I disagree with an issue resolution on the tracker?
+-----------------------------------------------------------
+
+First, take some time to consider any comments made in association with the
+resolution of the tracker issue. On reflection, they may seem more reasonable
+than they first appeared.
+
+If you still feel the resolution is incorrect, then raise the question on
+`python-dev`_. If the consensus there supports the disputed resolution, please
+take any further objections to `python-ideas`_ (or some other forum). Further
+argument on `python-dev`_ after a consensus has been reached amongst the core
+developers is unlikely to win any converts.
+
+
+How do I tell who is and isn't a core developer?
+------------------------------------------------
+
+You can check their name against the `full list of developers`_ with commit
+rights to the main source control repository.
+
+On the `issue tracker`_, most core developers will have the Python logo
+appear next to their name.
+
+.. _full list of developers: http://www.python.org/dev/committers
+
+
+What standards of behaviour are expected in these communication channels?
+-------------------------------------------------------------------------
+
+We try to foster environments of mutual respect, tolerance and encouragement,
+as described in the PSF's `Diversity Statement`_. Abiding by the guidelines
+in this document and asking questions or posting suggestions in the
+appropriate channels are an excellent way to get started on the mutual respect
+part, greatly increasing the chances of receiving tolerance and encouragement
+in return.
+
+.. _Diversity Statement: http://www.python.org/psf/diversity/
+
+
Version Control
-==================================
+===============
Where can I learn about the version control system used, Mercurial (hg)?
-------------------------------------------------------------------------------
diff --git a/help.rst b/help.rst
--- a/help.rst
+++ b/help.rst
@@ -5,31 +5,32 @@
If you are working on Python it is very possible you will come across an issue
where you need some assistance to solve it (this happens to core developers
-all the time). Below are some options on getting help.
+all the time).
-If the question involves process or tool usage then please check other parts of
-this guide first as it should answer your question.
+Should you require help, there are a :ref:`variety of options available
+<communication>` to seek assistance. If the question involves process or tool
+usage then please check the rest of this guide first (especially the
+:ref:`FAQ`) as it should answer your question.
-Ask (#)python-dev
+Ask #python-dev
-----------------
-You have two avenues of communication out of the :ref:`myriad of options
-available <communication>`. If you are comfortable with IRC you can try asking
-on ``#python-dev`` (on the `freenode <http://freenode.net/>`_ network).
-Typically there are a couple of experienced developers, ranging from
-triagers to core developers, who can answer questions about developing for
-Python. If you prefer email you can ask the `python-dev mailing-list
-<http://mail.python.org/mailman/listinfo/python-dev>`_ for help with your
-question. Just remember that both avenues are for questions involving the
-development *of* Python, **not** for development *with* Python.
+If you are comfortable with IRC you can try asking on ``#python-dev`` (on
+the `freenode`_ network). Typically there are a number of experienced
+developers, ranging from triagers to core developers, who can answer
+questions about developing for Python. Just remember that ``#python-dev``
+is for questions involving the development *of* Python whereas ``#python``
+is for questions concerning development *with* Python.
+
+.. _freenode: http://freenode.net/
File a Bug
----------
If you strongly suspect you have stumbled on a bug (be it in the build
-process, in the test suite, or in other areas), then open a issue on the
+process, in the test suite, or in other areas), then open an issue on the
`issue tracker`_. As with every bug report it is strongly advised that
you detail which conditions triggered it (including the OS name and version,
and what you were trying to do), as well as the exact error message you
@@ -37,3 +38,32 @@
.. _issue tracker: http://bugs.python.org
+
+Mailing Lists
+-------------
+
+Further options for seeking assistance include the `python-ideas`_ and
+`python-dev`_ mailing lists. Python-ideas contains discussion of speculative
+Python language ideas for possible inclusion into the language. If an idea
+gains traction it can then be discussed and honed to the point of becoming a
+solid proposal and presented on python-dev. Python-dev contains discussion
+of current Python design issues, release mechanics, and maintenance of
+existing releases. As with ``#python-dev``, these mailing lists are for
+questions involving the development *of* Python, **not** for development
+*with* Python.
+
+.. _python-ideas: http://mail.python.org/mailman/listinfo/python-ideas
+.. _python-dev: http://mail.python.org/mailman/listinfo/python-dev
+
+
+Core Mentorship
+---------------
+
+If you are interested in improving Python and contributing to its development,
+but don’t yet feel entirely comfortable with the public channels mentioned
+above, `Python Mentors`_ are here to help you. Python is fortunate to have a
+community of volunteer core developers willing to mentor anyone wishing to
+contribute code, work on bug fixes or improve documentation. Everyone is
+welcomed and encouraged to contribute.
+
+.. _Python Mentors: http://pythonmentors.com
diff --git a/index.rst b/index.rst
--- a/index.rst
+++ b/index.rst
@@ -50,18 +50,14 @@
------------
We encourage everyone to contribute to Python and that's why we have put up
-this developer's guide. You **should** read the following documents in
-the order provided. You can stop where you feel comfortable and begin
-contributing immediately without reading and understanding these documents all
-at once, but please do not skip around within the documentation as everything
-is written assuming preceding documentation has been read.
+this developer's guide. If you still have questions after reviewing the
+material in this guide, then the `Python Mentors`_ group is available to help
+guide new contributors through the process. The :doc:`Developer FAQ <faq>` is
+another useful source of information.
-You can, *however*, read the :doc:`FAQ <faq>` at any point!
+Guide for contributing to Python:
* :doc:`setup`
-* Coding style guides
- * `PEP 7`_ (Style Guide for C Code)
- * `PEP 8`_ (Style Guide for Python Code)
* :doc:`help`
* :doc:`patch`
* :doc:`runtests`
@@ -82,14 +78,54 @@
* :doc:`devcycle`
* :doc:`buildbots`
+It is **recommended** that the above documents be read in the order listed.
+You can stop where you feel comfortable and begin contributing immediately
+without reading and understanding these documents all at once. If you do
+choose to skip around within the documentation, be aware that it is written
+assuming preceding documentation has been read so you may find it necessary
+to backtrack to fill in missing concepts and terminology.
+
Proposing changes to Python itself
----------------------------------
+Improving Python's code, documentation and tests are ongoing tasks that are
+never going to be "finished", as Python operates as part of an ever-evolving
+system of technology. An even more challenging ongoing task than these
+necessary maintenance activities is finding ways to make Python, in the form
+of the standard library and the language definition, an even better tool in a
+developer's toolkit.
+
+While these kinds of change are much rarer than those described above, they do
+happen and that process is also described as part of this guide:
+
* :doc:`stdlibchanges`
* :doc:`langchanges`
+Other Interpreter Implementations
+---------------------------------
+
+This guide is specifically for contributing to the Python reference
+interpreter, also known as CPython (while most of the standard library is
+written in Python, the interpreter core is written in C and integrates most
+easily with the C and C++ ecosystems).
+
+There are other Python implementations, each with a different focus.
+Like CPython, they always have more things they would like to do than they
+have developers to work on them. Some major example that may of interest are:
+
+* PyPy_: A Python interpreter focused on high speed (JIT-compiled) operation
+ on major platforms
+* Jython_: A Python interpreter focused on good integration with the Java
+ Virtual Machine (JVM) environment
+* IronPython_: A Python interpreter focused on good integration with the
+ Common Language Runtime (CLR) provided by .NET and Mono
+* Stackless_: A Python interpreter focused on providing lightweight
+ microthreads while remaining largely compatible with CPython specific
+ extension modules
+
+
.. _resources:
@@ -99,6 +135,9 @@
* Anyone can checkout this guide from http://hg.python.org/devguide/.
Core developers should use ssh://hg@hg.python.org/devguide instead, so
that they can push back their edits to the server.
+* Coding style guides
+ * :PEP:`7` (Style Guide for C Code)
+ * :PEP:`8` (Style Guide for Python Code)
* `Issue tracker <http://bugs.python.org/>`_
* `Meta tracker <http://psf.upfronthosting.co.za/roundup/meta>`_ (issue
tracker for the issue tracker)
@@ -126,9 +165,12 @@
.. _Firefox search engine plug-in: http://www.python.org/dev/searchplugin/
.. _Misc directory: http://hg.python.org/cpython/file/tip/Misc
.. _PEPs: http://www.python.org/dev/peps
-.. _PEP 7: http://www.python.org/dev/peps/pep-0007
-.. _PEP 8: http://www.python.org/dev/peps/pep-0008
.. _python.org maintenance: http://python.org/dev/pydotorg/
+.. _Python Mentors: http://pythonmentors.com/
+.. _PyPy: http://www.pypy.org/
+.. _Jython: http://www.jython.org/
+.. _IronPython: http://ironpython.net/
+.. _Stackless: http://www.stackless.com/
Indices and tables
diff --git a/patch.rst b/patch.rst
--- a/patch.rst
+++ b/patch.rst
@@ -69,7 +69,7 @@
do to help ensure that your patch is accepted.
First, make sure to follow Python's style guidelines. For Python code you
-should follow `PEP 8`_, and for C code you should follow `PEP 7`_. If you have
+should follow :PEP:`8`, and for C code you should follow :PEP:`7`. If you have
one or two discrepencies those can be fixed by the core developer who commits
your patch. But if you have systematic deviations from the style guides your
patch will be put on hold until you fix the formatting issues.
@@ -104,8 +104,6 @@
.. _contributor form: http://www.python.org/psf/contrib/
-.. _PEP 7: http://www.python.org/dev/peps/pep-0007
-.. _PEP 8: http://www.python.org/dev/peps/pep-0008
.. _Python Software Foundation: http://www.python.org/psf/
--
Repository URL: http://hg.python.org/devguide
More information about the Python-checkins
mailing list