[Python-checkins] devguide: Various review comments. Also expand the SSH compression recommendation.

[ned.deily]

http://hg.python.org/devguide/rev/1b38c3e1ea75
changeset:   369:1b38c3e1ea75
user:        Ned Deily <nad at acm.org>
date:        Sat Mar 05 17:31:33 2011 -0800
summary:
  Various review comments. Also expand the SSH compression recommendation.

files:
  devcycle.rst
  faq.rst
  help.rst
  patch.rst
  runtests.rst
  setup.rst

diff --git a/devcycle.rst b/devcycle.rst
--- a/devcycle.rst
+++ b/devcycle.rst
@@ -94,7 +94,7 @@
 
 Based on what stage the :ref:`in-development <indevbranch>` version of Python
 is in, the responsibilities of a core developer change in regards to commits
-to the VCS.
+to the :abbr:`VCS (version control system)`.
 
 
 Pre-alpha
diff --git a/faq.rst b/faq.rst
--- a/faq.rst
+++ b/faq.rst
@@ -44,11 +44,13 @@
 are typically available either online or through the platform's package
 management system.
 
-It is recommended that you enable SSH compression.  In your ``.ssh/config``
-file, add the following lines::
+Mercurial does not use its own compression via SSH
+because it is better to enable compression at the SSH level.  Enabling
+SSH compression can make cloning a remote repository much faster.
+You can configure it in your ``~/.ssh/config`` file; for example::
 
-   Host *
-   Compression yes
+   Host hg.python.org
+     Compression yes
 
 .. _download Mercurial: http://mercurial.selenic.com/downloads/
 .. _OpenSSH: http://www.openssh.org/
diff --git a/help.rst b/help.rst
--- a/help.rst
+++ b/help.rst
@@ -4,8 +4,8 @@
 =================
 
 If you are working on Python it is very possible you will come across an issue
-where you need some assistance in solving (this happens to core developers all
-the time). Below are some options on getting help.
+where you need some assistance to solve it (this happens to core developers
+all the time). Below are some options on getting help.
 
 If the question involves process or tool usage then please check other parts of
 this guide first as it should answer your question.
diff --git a/patch.rst b/patch.rst
--- a/patch.rst
+++ b/patch.rst
@@ -138,7 +138,9 @@
 ----------
 
 If this is a patch in response to a pre-existing issue on the `issue tracker`_,
-attach the patch to the issue. Please provide any details about your patch that
+attach the patch to the issue; use the ``Choose File`` button on the tracker
+web page for the issue to upload your patch file. Please provide any details
+about your patch that
 would be relevant to the discussion of the issue or your patch.
 
 If this is a patch for an unreported issue (assuming you already performed a
@@ -155,8 +157,8 @@
 ---------
 
 To begin with, please be patient! There are many more people submitting patches
-than there are people capable of reviewing your patch. To get your patch
-reviewed it requires a reviewer to have the spare time and motivation to
+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
@@ -178,7 +180,8 @@
 your patch is committed. Balancing what *does* and *does not* go into Python
 is tricky and we simply cannot accept everyone's contributions.
 
-But if your patch is committed it will then go into Python's VCS to be released
+But if your patch is committed it will then go into Python's
+:abbr:`VCS (version control system)` to be released
 with the next major release of Python. It may also be backported to older
 versions of Python as a bugfix if the core developer doing the commit believes
 it is warranted.
diff --git a/runtests.rst b/runtests.rst
--- a/runtests.rst
+++ b/runtests.rst
@@ -4,7 +4,8 @@
 =======================
 
 .. note::
-    This document assumes you are working from a checkout of Python. If you
+    This document assumes you are working from an
+    :ref:`in-development <indevbranch>` checkout of Python. If you
     are not then some things presented here may not work as they may depend
     on new features not available in earlier versions of Python.
 
@@ -49,10 +50,11 @@
 test
 suite has not reached a point where all warnings have been dealt with and so we
 cannot guarantee that a bug-free Python will properly complete a test run with
-``-W error``). The ``-r`` flag to the test runner causes it to run more randomly
-which helps assert that the various tests don't interfere against each other.
-The ``-w`` flag causes failures to run again to see if it a transient failure
-or a consistent one. The ``-uall`` flag allows the user of all available
+``-W error``). The ``-r`` flag to the test runner causes it to run tests in a
+more random order which helps to check that the various tests do not interfere
+with each other.  The ``-w`` flag causes failing tests to be run again to see
+if the failures are transient or consistent.
+The ``-uall`` flag allows the use of all available
 resources so as to not skip tests requiring, e.g., Internet access.
 
 
diff --git a/setup.rst b/setup.rst
--- a/setup.rst
+++ b/setup.rst
@@ -31,7 +31,7 @@
 be tempting to work from the copy of Python you already have installed on your
 machine, it is very likely that you will be working from out-of-date code as
 the Python core developers are constantly updating and fixing things in their
-:abbr:`VCS`. It also means you will have better tool
+:abbr:`VCS (version control system)`. It also means you will have better tool
 support through the VCS as it will provide a diff tool, etc.
 
 To get a working copy of the :ref:`in-development <indevbranch>` branch of
@@ -49,8 +49,10 @@
 You will need to re-compile CPython when you do such an update.
 
 Do note that CPython will notice that it is being run from a working copy.
-This means that it if you edit CPython's source code in your working copy the
-changes will be picked up by the interpreter for immediate use and testing.
+This means that it if you edit CPython's source code in your working copy,
+changes to Python code will be picked up by the interpreter for immediate
+use and testing.  (If you change C code, you will need to recompile the
+affected files as described below.)
 
 
 Compiling (for debugging)
@@ -123,7 +125,7 @@
 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
 all examples), ``./python.exe`` on OS X (when on a case-insensitive filesystem,
-which is the default). There is absolutely no need to install your built copy
+which is the default). There is normally no need to install your built copy
 of Python! The interpreter will realize where it is being run from
 and thus use the files found in the working copy. If you are worried
 you might accidentally install your working copy build, you can add

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