iSharkFly-Open
/
python-peps
mirror of https://github.com/python/peps.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Clean up whitespace.

This commit is contained in:
Brett Cannon 2009-01-27 20:14:27 +00:00
parent 347396990d
commit ff2c34ceb7
1 changed files with 183 additions and 183 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

224
pep-0374.txt
View File

@ -39,7 +39,7 @@ custom version, do not have direct tool support for revisions. This
can be quite a limitation, since these non-core developers cannot do
easily do basic tasks such as reverting changes to a previously
saved state, creating branches, publishing one's changes with full
revision history, etc.  For non-core developers, the last safe tree
revision history, etc. For non-core developers, the last safe tree
state is one the Python developers happen to set, and this prevents
safe development. This second-class citizenship is a hindrance to
people who wish to contribute to Python with a patch of any
@ -56,12 +56,12 @@ bad Internet connection where committing is time-consuming and
expensive and it might work out better to do it in a single step.
Another drawback to a centralized VCS is that a common use case is
for a developer to revise patches in response to review comments. 
for a developer to revise patches in response to review comments.
This is more difficult with a centralized model because there's no
place to contain intermediate work.  It's either all checked in or
none of it is checked in.  In the centralized VCS, it's also very
place to contain intermediate work. It's either all checked in or
none of it is checked in. In the centralized VCS, it's also very
difficult to track changes to the trunk as they are committed, while
you're working on your feature or bug fix branch.  This increases
you're working on your feature or bug fix branch. This increases
the risk that such branches will grow stale, out-dated, or that
merging them into the trunk will generate too may conflicts to be
easily resolved.
@ -76,10 +76,10 @@ worked on). Once a release is done, a branch is created between the
code bases where changes in one version do not (but could) belong in
the other version. As of right now there is no natural support for
this branch in time in central VCSs; you must use tools that
simulate the branching.  Tracking merges is similarly painful for
simulate the branching. Tracking merges is similarly painful for
developers, as revisions often need to be merged between four active
branches (e.g. 2.6 maintenance, 3.0 maintenance, 2.7 development,
3.1 development).  In this case, VCSs such as Subversion only handle
3.1 development). In this case, VCSs such as Subversion only handle
this through arcane third party tools.
Distributed VCSs (DVCSs) solve all of these problems. While one can
@ -88,7 +88,7 @@ tree for their own use. This gives everyone the power to commit
changes to their copy, online or offline. It also more naturally
ties into the idea of branching in the history of a revision tree
for maintenance and the development of new features bound for
Python.  DVCSs also provide a great many additional features that
Python. DVCSs also provide a great many additional features that
centralized VCSs don't or can't provide.
This PEP explores the possibility of changing Python's use of Subversion
@ -105,9 +105,9 @@ Terminology
Agreeing on a common terminology is surprisingly difficult,
primarily because each VCS uses these terms when describing subtly
different tasks, objects, and concepts.  Where possible, we try to
different tasks, objects, and concepts. Where possible, we try to
provide a generic definition of the concepts, but you should consult
the individual system's glossaries for details.  Here are some basic
the individual system's glossaries for details. Here are some basic
references for terminology, from some of the standard web-based
references on each VCS. You can also refer to glossaries for each
DVCS:
@ -191,9 +191,9 @@ being able to commit locally at the speed of your disk, a core
developer is able to do atomic commits much more frequently,
minimizing having commits that do multiple things to the code. Also
by using a branch, the changes are isolated (if desired) from other
changes being made by other developers.  Because branches are cheap,
changes being made by other developers. Because branches are cheap,
it is easy to create and maintain many smaller branches that address
one specific issue, e.g. one bug or one new feature.  More
one specific issue, e.g. one bug or one new feature. More
sophisticated features of DVCSs allow the developer to more easily
track long running development branches as the official mainline
progresses.
@ -206,7 +206,7 @@ Contenders
Name Short Name Version 2.x Trunk Mirror 3.x Trunk Mirror
---------- ---------- ------- ----------------------------------- ------------------------------------------
Bazaar_ bzr 1.11 http://code.python.org/python/trunk http://code.python.org/python/3.0
Mercurial_ hg 1.1.2 http://code.python.org/hg/trunk/ http://code.python.org/hg/branches/py3k/
Mercurial_ hg 1.1.2 http://code.python.org/hg/trunk/ http://code.python.org/hg/branches/py3k/
git_ N/A 1.6.1 git://code.python.org/python/trunk git://code.python.org/python/branches/py3k
========== ========== ======= =================================== ==========================================
@ -217,7 +217,7 @@ git_ N/A 1.6.1 git://code.python.org/python/trunk git://code.pyt
This PEP does not consider darcs, arch, or monotone. The main
problem with these DVCSs is that they are simply not popular enough
to bother supporting when they do not provide some very compelling
features that the other DVCSs provide.  Arch and darcs also have
features that the other DVCSs provide. Arch and darcs also have
significant performance problems which seem unlikely to be addressed
in the near future.
@ -255,17 +255,17 @@ scenarios are run in order to take better advantage of the tools.
All of the DVCSs support configuring your project identification.
Unlike the centralized systems, they use your email address to
identify your commits.  (Access control is generally done by
identify your commits. (Access control is generally done by
mechanisms external to the DVCS, such as ssh or console login).
This identity may be associated with a full name. 
This identity may be associated with a full name.
All of the DVCSs will query the system to get some approximation to
this information, but that may not be what you want.  They also
this information, but that may not be what you want. They also
support setting this information on a per-user basis, and on a per-
project basis.  Convenience commands to set these attributes vary,
project basis. Convenience commands to set these attributes vary,
but all allow direct editing of configuration files.
Some VCSs support end-of-line (EOL) conversions on checkout/checkin.  
Some VCSs support end-of-line (EOL) conversions on checkout/checkin.
svn
@ -281,15 +281,15 @@ bzr
No setup is required, but for much quicker and space-efficient local
branching, you should create a shared repository to hold all your
Python branches.  A shared repository is really just a parent
directory containing a .bzr directory.  When bzr commits a revision,
Python branches. A shared repository is really just a parent
directory containing a .bzr directory. When bzr commits a revision,
it searches from the local directory on up the file system for a .bzr
directory to hold the revision.  By sharing revisions across multiple
branches, you cut down on the amount of disk space used.  Do this::
directory to hold the revision. By sharing revisions across multiple
branches, you cut down on the amount of disk space used. Do this::
  cd ~/projects
  bzr init-repo python
  cd python
cd ~/projects
bzr init-repo python
cd python
Now, all your Python branches should be created inside of
``~/projects/python``.
@ -297,18 +297,18 @@ Now, all your Python branches should be created inside of
There are also some settings you can put in your
``~/.bzr/bazaar.conf``
and ``~/.bzr/locations.conf`` file to set up defaults for interacting
with Python code.  None of them are required, although some are
recommended.  E.g. I would suggest gpg signing all commits, but that
might be too high a barrier for developers.  Also, you can set up
with Python code. None of them are required, although some are
recommended. E.g. I would suggest gpg signing all commits, but that
might be too high a barrier for developers. Also, you can set up
default push locations depending on where you want to push branches
by default.  If you have write access to the master branches, that
push location could be code.python.org.  Otherwise, it might be a
free Bazaar code hosting service such as Launchpad.  If Bazaar is
by default. If you have write access to the master branches, that
push location could be code.python.org. Otherwise, it might be a
free Bazaar code hosting service such as Launchpad. If Bazaar is
chosen, we should decide what the policies and recommendations are.
At a minimum, I would set up your email address::
  bzr whoami "Firstname Lastname <email.address@example.com>"
bzr whoami "Firstname Lastname <email.address@example.com>"
hg
@ -317,14 +317,14 @@ hg
Minimally, you should set your user name. To do so, create the file
``.hgrc`` in your home directory and add the following::
 [ui]
 username = Firstname Lastname <email.address@example.com>
[ui]
username = Firstname Lastname <email.address@example.com>
If you are using Windows, enable the win32text extension to use
Unix-style newlines by adding to your configuration::
 [extensions]
 win32text =
[extensions]
win32text =
These options can also be set locally to a given repository by
customizing ``<repo>/.hg/hgrc``, instead of ``~/.hgrc``.
@ -333,10 +333,10 @@ customizing ``<repo>/.hg/hgrc``, instead of ``~/.hgrc``.
git
'''
None needed.  However, git supports a number of features that can
smooth your work, with a little preparation.  git supports setting
defaults at the workspace, user, and system levels.  The system
level is out of scope of this PEP.  The user configuration file is
None needed. However, git supports a number of features that can
smooth your work, with a little preparation. git supports setting
defaults at the workspace, user, and system levels. The system
level is out of scope of this PEP. The user configuration file is
``$HOME/.gitconfig`` on Unix-like systems, and the workspace
configuration file is ``$REPOSITORY/.git/config``.
@ -355,7 +355,7 @@ Mercurial section above).::
git config user.email email.address@python.example.com
If you are using Windows, you probably want to set the core.autocrlf
and core.safecrlf preferences to true using ``git-config``.::
and core.safecrlf preferences to true using ``git-config``.::
# check out files with CRLF line endings rather than Unix-style LF only
git config --global core.autocrlf true
@ -379,16 +379,16 @@ specify.::
echo '.msg' >> ~/.gitignore
If you use multiple branches, you can save a lot of space by putting
all objects in a common object store.  This can be done physically,
all objects in a common object store. This can be done physically,
by making them branches in a single repository. It can alternatively
be done logically, with the environment variables
``GIT_OBJECT_DIRECTORY`` (a single directory where new repository
objects will be written) and ``GIT_ALTERNATE_OBJECT_DIRECTORIES``
(a colon-separated path -- on Windows, semicolon-separated -- of
directories containing read-only object stores to search).  Note that
directories containing read-only object stores to search). Note that
when making a local clone, git will hard-link objects rather than
creating copies if the OS supports that, which also saves space in
the child repository.  Here's a complicated example::
the child repository. Here's a complicated example::
# clone the trunk and py3k repositories
cd /path/to/myrepos
@ -402,7 +402,7 @@ the child repository.  Here's a complicated example::
# set up environment for my personal copy of py3k
# read/write: if a file introduced in py3k is imported to trunk
# verbatim, the trunk sandbox will
# use the object created in the py3k sandbox
# use the object created in the py3k sandbox
export GIT_OBJECT_DIRECTORY=/path/to/myrepos/trunk-sandbox
git clone py3k py3k-sandbox
@ -486,12 +486,12 @@ git
'''
The patches could be created with
``git diff master > stuff-i-did.patch``, too, but
``git diff master > stuff-i-did.patch``, too, but
``git format-patch | git am`` knows some tricks
(empty files, renames, etc) that ordinary patch can't handle.  git
(empty files, renames, etc) that ordinary patch can't handle. git
grabs "Stuff I did" out of the the commit message to create the file
name 0001-Stuff-I-did.patch.  See Patch Review below for a
description of the git-format-patch format.::
name 0001-Stuff-I-did.patch. See Patch Review below for a
description of the git-format-patch format.::
# Get the mainline code.
git clone git://code.python.org/python/trunk
@ -565,10 +565,10 @@ git
# Assume the change to revert is the grandfather of a revision tagged "newhotness".
git revert newhotness~2
#if CONFLICTS
#    Resolve conflicts if any.
git commit -m "Reverted changeset 9150dd9c6d30."
# Resolve conflicts if any.
git commit -m "Reverted changeset 9150dd9c6d30."
#else
#    Edit log message, commit will be done automatically.
# Edit log message, commit will be done automatically.
#endif
git push
@ -629,10 +629,10 @@ bzr
rm -rf ../issueNNNN
Alternatively, since you're probably going to commit these changes to
the trunk, you could just do a checkout.  That would give you a local
the trunk, you could just do a checkout. That would give you a local
working tree while the branch (i.e. all revisions) would continue to
live on the server.  This is similar to the svn model and might allow
you to more quickly review the patch.  There's no need for the push
live on the server. This is similar to the svn model and might allow
you to more quickly review the patch. There's no need for the push
in this case.::
bzr checkout trunk issueNNNN
@ -660,11 +660,11 @@ hg
git
'''
We assume a patch created by git-format-patch.  This is a Unix mbox
We assume a patch created by git-format-patch. This is a Unix mbox
file containing one or more patches, each formatted as an RFC 2822
message.  git-am interprets each message as a commit as follows.  The
message. git-am interprets each message as a commit as follows. The
author of the patch is taken from the From: header, the date from the
Date header.  The commit log is created by concatenating the content
Date header. The commit log is created by concatenating the content
of the subject line, a blank line, and the message body up to the
start of the patch.::
@ -672,7 +672,7 @@ start of the patch.::
# Create a branch in case we don't like the patch.
git checkout -b patch-review
# Download patch from bugs.python.org to submitted.patch.
git am « submitted.patch
git am < submitted.patch
# Review and approve patch.
# Merge into master and push.
git checkout master
@ -724,9 +724,9 @@ bzr
'''
Bazaar is pretty straightforward here, since it supports cherry
picking revisions manually.  In the example below, we could have
picking revisions manually. In the example below, we could have
given a revision id instead of a revision number, but that's usually
not necessary.  Martin Pool suggests "We'd generally recommend doing
not necessary. Martin Pool suggests "We'd generally recommend doing
the fix first in the oldest supported branch, and then merging it
forward to the later releases."::
@ -808,7 +808,7 @@ git
'''
In git I would have an "integration" workspace which contains all of
the relevant master repository branches.  git cherry-pick doesn't
the relevant master repository branches. git cherry-pick doesn't
work across repositories; you need to have the branches in the same
repository.
::
@ -821,26 +821,26 @@ repository.
git cherry-pick -x release27~3
# If there are conflicts, resolve them, and commit those changes.
# git commit -a -m "Resolve conflicts."
# Run test suite.  If fixes are necessary, record as a separate commit.
# Run test suite. If fixes are necessary, record as a separate commit.
# git commit -a -m "Fix code causing test failures."
git checkout master
git cherry-pick -x release27~3
# Do any conflict resolution and test failure fixups.
# Revert Misc/NEWS changes.
git checkout HEAD^ -- Misc/NEWS
# This creates a new commit on top of the cherry-pick.  An alternative workflow
# would use the -n (aka --no-commit) flag to git-cherry-pick, and then commit
# This creates a new commit on top of the cherry-pick. An alternative workflow
# would use the -n (aka --no-commit)flag to git-cherry-pick, and then commit
# here with an appropriate log message.
git commit -m 'Revert cherry-picked Misc/NEWS changes.' Misc/NEWS
# Push both ports.
git push release26 master
If you are regularly merging (rather than cherry-picking) from a
If you are regularly merging (rather than cherry-picking) from a
given branch, then you can block a given commit from being
accidentally merged in the future by merging, then reverting it.
This does not prevent a cherry-pick from pulling in the unwanted
patch, and this technique requires blocking everything that you don't
want merged.  I'm not sure if this differs from svn on this point.
want merged. I'm not sure if this differs from svn on this point.
::
cd trunk
@ -848,7 +848,7 @@ want merged.  I'm not sure if this differs from svn on this point.
git merge experimental-branch
# We don't want the 3rd-to-last commit from the experimental-branch,
# and we don't want it to ever be merged.
# The notation "^N" means Nth parent of the current commit.  Thus HEAD^2^1^1
# The notation "^N" means Nth parent of the current commit. Thus HEAD^2^1^1
# means the first parent of the first parent of the second parent of HEAD.
git revert HEAD^2^1^1
# Propagate the merge and the prohibition to the public repository.
@ -859,14 +859,14 @@ Coordinated Development of a New Feature
----------------------------------------
Sometimes core developers end up working on a major feature with
several developers.  As a core developer, I want to be able to
several developers. As a core developer, I want to be able to
publish feature branches to a common public location so that I can
collaborate with other developers.
This requires creating a branch on a server that other developers
can access.  All of the DVCSs support creating new repositories on
can access. All of the DVCSs support creating new repositories on
hosts where the developer is already able to commit, with
appropriate configuration of the repository host. This is
appropriate configuration of the repository host. This is
similar in concept to the existing sandbox in svn, although details
of repository initialization may differ.
@ -984,7 +984,7 @@ fix the socket bugs.
bzr branch bzr+svn://trunk bug-0000
cd bug-0000
# Edit some code.  Dang, we need to fix the socket module.
# Edit some code. Dang, we need to fix the socket module.
bzr shelve --all
# Edit some code.
bzr commit -m "Socket module fixes"
@ -992,15 +992,15 @@ fix the socket bugs.
bzr unshelve
# Edit some code
Another approach one might take uses the loom plugin.  Looms can
Another approach one might take uses the loom plugin. Looms can
greatly simply working on dependent branches because they
automatically take care of the stacking dependencies for you. 
automatically take care of the stacking dependencies for you.
Imagine looms as a stack of dependent branches (called "threads" in
loom parlance), with easy ways to move up and down the stack of
thread, merge changes up the stack to descendant threads, create
diffs between threads, etc.  Occasionally, you may need or want to
diffs between threads, etc. Occasionally, you may need or want to
export your loom threads into separate branches, either for review
or commit.  Higher threads incorporate all the changes in the lower
or commit. Higher threads incorporate all the changes in the lower
threads, automatically.
::
@ -1008,7 +1008,7 @@ threads, automatically.
cd bug-0000
bzr loomify trunk
bzr create-thread fix-urllib
# Edit some code.  Dang, we need to fix the socket module.
# Edit some code. Dang, we need to fix the socket module.
bzr commit -m "Checkpointing my work so far"
bzr down-thread
bzr create-thread fix-socket
@ -1022,20 +1022,20 @@ threads, automatically.
bzr record done
For bonus points, let's say someone else fixes the socket module in
exactly the same way you did.  Perhaps this person even grabbed your
fix-socket thread and applied just that to the trunk.  You'd like to
exactly the same way you did. Perhaps this person even grabbed your
fix-socket thread and applied just that to the trunk. You'd like to
be able to merge their changes into your loom and delete your
now-redundant fix-socket thread.
::
bzr down-thread trunk
# Get all new revisions to the trunk.  If you've done things
# Get all new revisions to the trunk. If you've done things
# correctly, this must succeed without conflict.
bzr pull
bzr up-thread
# See?  The fix-socket thread is now identical to the trunk
# See? The fix-socket thread is now identical to the trunk
bzr commit -m 'Merge in trunk changes'
bzr diff -r thread: | wc -l  # returns 0
bzr diff -r thread: | wc -l # returns 0
bzr combine-thread
bzr up-thread
# Resolve any conflicts
@ -1065,7 +1065,7 @@ hg
hg merge
hg push
cd ..
rm -rf issue0000 fix-socket-bug
rm -rf issue0000 fix-socket-bug
git
@ -1110,16 +1110,16 @@ git
git reset --hard checkpoint
git pull git://code.python.org/public/trunk master
git rebase --onto master fix-socket bug-0000
# If there were any conflicts, we fixed them during rebase.  But
# If there were any conflicts, we fixed them during rebase. But
# there shouldn't be any,
# since we assumed the socket bug is independent of the urllib bug.
git checkout master
git merge bug-0000
git push
# Clean up.  We don't delete bug-0000 because the merge obsoleted it already.
# Clean up. We don't delete bug-0000 because the merge obsoleted it already.
git tag -d checkpoint
git branch -d fix-socket
# Now our HEAD has an up-to-date trunk and just the urllib fix.
# Now our HEAD has an up-to-date trunk and just the urllib fix.
Doing a Python Release
@ -1131,15 +1131,15 @@ How does PEP 101 change when using a DVCS?
bzr
'''
It will change, but not substantially so.  When doing the
It will change, but not substantially so. When doing the
maintenance branch, we'll just push to the new location instead of
doing an svn cp.  Tags are totally different, since in svn they are
doing an svn cp. Tags are totally different, since in svn they are
directory copies, but in bzr (and I'm guessing hg), they are just
symbolic names for revisions on a particular branch.  The release.py
script will have to change to use bzr commands instead.  It's
symbolic names for revisions on a particular branch. The release.py
script will have to change to use bzr commands instead. It's
possible that because DVCS (in particular, bzr) does cherry picking
and merging well enough that we'll be able to create the maint
branches sooner.  It would be a useful exercise to try to do a
branches sooner. It would be a useful exercise to try to do a
release off the bzr/hg mirrors.
@ -1159,17 +1159,17 @@ revision.
git
'''
It will change, but not substantially so.  When doing the
It will change, but not substantially so. When doing the
maintenance branch, we'll just git push to the new location instead
of doing an svn cp.  Tags are totally different, since in svn they
of doing an svn cp. Tags are totally different, since in svn they
are directory copies, but in git they are just symbolic names for
revisions, as are branches.  (The difference between a tag and a
revisions, as are branches. (The difference between a tag and a
branch is that tags refer to a particular commit, and will never
change unless you use git tag -f to force them to move.  The
change unless you use git tag -f to force them to move. The
checked-out branch, on the other hand, is automatically updated by
git commit.)  The release.py script will have to change to use git
commands instead.  With git I would create a (local) maintenance
branch as soon as the release engineer is chosen.  Then I'd "git
git commit.) The release.py script will have to change to use git
commands instead. With git I would create a (local) maintenance
branch as soon as the release engineer is chosen. Then I'd "git
pull" until I didn't like a patch, when it would be "git pull; git
revert ugly-patch", until it started to look like the sensible thing
is to fork off, and start doing "git cherry-pick" on the good
@ -1207,7 +1207,7 @@ CRLF -> LF Support
bzr
My understanding is that support for this is being worked on as
I type, landing in a version RSN.  I will try to dig up details.
I type, landing in a version RSN. I will try to dig up details.
hg
Supported via the win32text extension.
@ -1222,8 +1222,8 @@ Case-insensitive filesystem support
-----------------------------------
bzr
Should be OK.  I share branches between Linux and OS all the
time.  I've done case changes (e.g. bzr mv Mailman mailman) and
Should be OK. I share branches between Linux and OS all the
time. I've done case changes (e.g. bzr mv Mailman mailman) and
as long as I did it on Linux (obviously), when I pulled in the
changes on OS X everything was hunky dory.
@ -1236,7 +1236,7 @@ git
git does not have a problem with renames in either direction.
However, case-insensitive filesystem support is usually taken
to mean complaining about collisions on case-sensitive files
systems.  git does not do that.
systems. git does not do that.
Tools
@ -1244,9 +1244,9 @@ Tools
In terms of code review tools such as `Review Board`_ and Rietveld_,
the former supports all three while the latter supports hg and git but
not bzr.  Bazaar does not yet have an online review board, but it
has several ways to manage email based reviews and trunk merging. 
There's `Bundle Buggy`_, `Patch Queue Manager`_ (PQM), and
not bzr. Bazaar does not yet have an online review board, but it
has several ways to manage email based reviews and trunk merging.
There's `Bundle Buggy`_, `Patch Queue Manager`_ (PQM), and
`Launchpad's code reviews <https://launchpad.net/+tour/code-review>`_.
.. _Review Board: http://www.review-board.org/
@ -1327,7 +1327,7 @@ bzr
Martin Pool adds: "bzr has a stable Python scripting interface, with
a distinction between public and private interfaces and a
deprecation window for APIs that are changing.  Some plugins are
deprecation window for APIs that are changing. Some plugins are
listed in https://edge.launchpad.net/bazaar and
http://bazaar-vcs.org/Documentation".
@ -1347,7 +1347,7 @@ git
---
git has a cvsserver mode, ie, you can check out a tree from git
using CVS.  You can even commit to the tree, but features like
using CVS. You can even commit to the tree, but features like
merging are absent, and branches are handled as CVS modules, which
is likely to shock a veteran CVS user.
@ -1374,12 +1374,12 @@ developer. Timings were done using the ``time`` command in zsh and
space was calculated with ``du -c -h``.
======= ================ ==============
DVCS Time Space
DVCS Time Space
------- ---------------- --------------
svn 1:04 139 M
svn 1:04 139 M
bzr 10:45 276 M
hg 2:30 171 M
git 2:54 134 M
hg 2:30 171 M
git 2:54 134 M
======= ================ ==============
.. note::