From ff2c34ceb7239242fa3aa9fb33be2323a918fbec Mon Sep 17 00:00:00 2001 From: Brett Cannon Date: Tue, 27 Jan 2009 20:14:27 +0000 Subject: [PATCH] Clean up whitespace. --- pep-0374.txt | 366 +++++++++++++++++++++++++-------------------------- 1 file changed, 183 insertions(+), 183 deletions(-) diff --git a/pep-0374.txt b/pep-0374.txt index ec1577b3a..9d7aaf7ee 100644 --- a/pep-0374.txt +++ b/pep-0374.txt @@ -18,7 +18,7 @@ Post-History: 07-Nov-2008 development. -Rationale +Rationale ========= Python has been using a centralized version control system (VCS; @@ -28,7 +28,7 @@ place to always get the official Python source code. It has also allowed for the storage of the history of the language, mostly for help with development, but also for posterity. And of course the V in VCS is very helpful when developing. - + But a centralized version control system has its drawbacks. First and foremost, in order to have the benefits of version control with Python in a seamless fashion, one must be a "core developer" (i.e. @@ -39,13 +39,13 @@ 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 complexity and want a way to incrementally save their progress to make their development lives easier. - + There is also the issue of having to be online to be able to commit one's work. Because centralized VCSs keep a central copy that stores all revisions, one must have Internet access in order for their @@ -54,18 +54,18 @@ you happen to be traveling and lack any Internet. There is also the situation of someone wishing to contribute to Python but having a 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. - + Lastly, there is the issue of maintenance of Python. At any one time there is at least one major version of Python under development (at the time of this writing there are two). For each major version of @@ -76,11 +76,11 @@ 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 -this through arcane third party tools. +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 keep a master copy of a revision tree, anyone is free to copy that @@ -88,9 +88,9 @@ 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 to any of the currently popular DVCSs, in order to gain the benefits outlined above. This PEP does not guarantee that a switch @@ -98,16 +98,16 @@ to a DVCS will occur at the conclusion of this PEP. It is quite possible that no clear winner will be found and that svn will continue to be used. If this happens, this PEP will be revisited and revised in the future as the state of DVCSs evolves. - -Terminology + +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: @@ -120,56 +120,56 @@ DVCS: -branch +branch A line of development; a collection of revisions, ordered by time. -checkout/working copy/working tree +checkout/working copy/working tree A tree of code the developer can edit, linked to a branch. -index +index A "staging area" where a revision is built (unique to git). -repository +repository A collection of revisions, organized into branches. -clone +clone A complete copy of a branch or repository. commit To record a revision in a repository. -merge +merge Applying all the changes and history from one branch/repository to another. -pull +pull To update a checkout/clone from the original branch/repository, - which can be remote or local + which can be remote or local -push/publish +push/publish To copy a revision, and all revisions it depends on, from a one repository to another. -cherry-pick +cherry-pick To merge one or more specific revisions from one branch to another, possibly in a different repository, possibly without its dependent revisions. -rebase +rebase To "detach" a branch, and move it to a new branch point; move commits to the beginning of a branch instead of where they happened in time. -Typical Workflow +Typical Workflow ================ At the moment, the typical workflow for a Python core developer is: - -* Edit code in a checkout until it is stable enough to commit/push. -* Commit to the master repository. + +* Edit code in a checkout until it is stable enough to commit/push. +* Commit to the master repository. It is a rather simple workflow, but it has drawbacks. For one, because any work that involves the repository takes time thanks to @@ -177,11 +177,11 @@ the network, commits/pushes tend to not necessarily be as atomic as possible. There is also the drawback of there not being a necessarily cheap way to create new checkouts beyond a recursive copy of the checkout directory. - + A DVCS would lead to a workflow more like this: - -* Branch off of a local clone of the master repository. -* Edit code, committing in atomic pieces. + +* Branch off of a local clone of the master repository. +* Edit code, committing in atomic pieces. * Merge the branch into the mainline, and * Push all commits to the master repository. @@ -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,18 +255,18 @@ 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 " + bzr whoami "Firstname Lastname " 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 + [ui] + username = Firstname Lastname 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 ``/.hg/hgrc``, instead of ``~/.hgrc``. @@ -333,10 +333,10 @@ customizing ``/.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``. @@ -353,9 +353,9 @@ Mercurial section above).:: # but use my Pythonic email address cd /path/to/python/repository 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,13 +402,13 @@ 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 If you want more complexity, git clone has a plethora of options to optimize space. - + One-Off Checkout ---------------- @@ -416,7 +416,7 @@ One-Off Checkout As a non-core developer, I want to create and publish a one-off patch that fixes a bug, so that a core developer can review it for inclusion in the mainline. - + * Checkout/branch/clone trunk. * Edit some code. * Generate a patch (based on what is best supported by the VCS, e.g. @@ -445,10 +445,10 @@ svn svn diff >> patch-2.diff # Upload patch-2 to bugs.python.org - + bzr ''' -:: +:: bzr branch http://code.python.org/python/trunk cd trunk @@ -462,10 +462,10 @@ bzr bzr send -o bundle # Upload updated bundle to bugs.python.org - + hg '' -:: +:: hg clone http://code.python.org/hg/trunk cd trunk @@ -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 @@ -517,10 +517,10 @@ Backing Out Changes As a core developer, I want to undo a change that was not ready for inclusion in the mainline. - + * Back out the unwanted change. * Push patch to server. - + svn ''' @@ -530,7 +530,7 @@ svn svn merge -c -40 . # Resolve conflicts, if any. svn commit -m "Reverted revision 40" - + bzr ''' @@ -540,10 +540,10 @@ bzr bzr merge -r 40..39 # Resolve conflicts, if any. bzr commit -m "Reverted revision 40" - + Note that if the change you want revert is the last one that was made, you can just use ``bzr uncommit``. - + hg '' @@ -554,7 +554,7 @@ hg # Resolve conflicts, if any. hg commit -m "Reverted changeset 9150dd9c6d30" hg push - + Note, you can use "hg rollback" and "hg strip" to revert changes you committed in your local repository, but did not yet push to other repositories. @@ -565,13 +565,13 @@ 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 - + Patch Review ------------ @@ -602,7 +602,7 @@ core developers have not taken the "branch on the server" approach to dealing with individual patches. For this scenario the assumption will be the developer creates a local checkout of the trunk to work with.:: - + cp -r trunk issue0000 cd issue0000 patch -p0 < __patch__ @@ -614,11 +614,11 @@ with.:: Another option is to only have a single checkout running at any one time and use ``svn diff`` along with ``svn revert -R`` to store away independent changes you may have made. - + bzr ''' -:: +:: bzr branch trunk issueNNNN # Download `patch` bundle from Roundup @@ -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 @@ -641,30 +641,30 @@ in this case.:: # Review patch bzr commit -m'Patch NNNN by So N. So' --fixes python:NNNN rm -rf ../issueNNNN - + hg '' -:: +:: hg clone trunk issue0000 cd issue0000 # If the patch was generated using hg export, the user name of the - # submitter is automatically recorded. Otherwise, + # submitter is automatically recorded. Otherwise, # use hg import --no-commit submitted.diff and commit with # hg commit -u "Firstname Lastname " hg import submitted.diff # Review patch. hg push ssh://alexandre@code.python.org/hg/trunk/ - + 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,25 +848,25 @@ 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. git push - + 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. @@ -885,7 +885,7 @@ CGI interfaces for developers who maintain their own servers. .. _Launchpad: http://www.launchpad.net/ .. _bitbucket.org: http://www.bitbucket.org/ .. _GitHub: http://www.github.com/ - + * Branch trunk. * Pull from branch on the server. * Pull from trunk. @@ -907,11 +907,11 @@ svn # Pull in trunk and merge to the branch. svnmerge merge svn commit -F svnmerge-commit-message.txt - + bzr ''' -:: +:: XXX To be done by Brett as a test of knowledge and online documentation/community. @@ -939,7 +939,7 @@ smaller issues. Being able to take the current work and then begin working on a separate issue is very helpful to separate out issues into individual units of work instead of compounding them into a single, large unit. - + * Create a branch A (e.g. urllib has a bug). * Edit some code. * Create a new branch B that branch A depends on (e.g. the urllib @@ -974,7 +974,7 @@ also no way to express dependencies between changelists. cd .. rm -rf issue0000 - + bzr ''' Here's an approach that uses bzr shelf (now a standard part of bzr) @@ -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,27 +1022,27 @@ 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 bzr commit -m 'Merge trunk' # Now our top-thread has an up-to-date trunk and just the urllib fix. - + hg '' :: @@ -1065,9 +1065,9 @@ hg hg merge hg push cd .. - rm -rf issue0000 fix-socket-bug + rm -rf issue0000 fix-socket-bug + - git ''' :: @@ -1110,39 +1110,39 @@ 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 ---------------------- 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. - - + + hg '' @@ -1159,22 +1159,22 @@ 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 patches. - + Platform/Tool Support ===================== @@ -1182,8 +1182,8 @@ Platform/Tool Support Operating Systems ----------------- ==== ======================================= ============================================= ============================= -DVCS Windows OS X UNIX ----- --------------------------------------- --------------------------------------------- ----------------------------- +DVCS Windows OS X UNIX +---- --------------------------------------- --------------------------------------------- ----------------------------- bzr yes (installer) w/ tortoise yes (installer, fink or MacPorts) yes (various package formats) hg yes (third-party installer) w/ tortoise yes (third-party installer, fink or MacPorts) yes (various package formats) git yes (third-party installer) yes (third-party installer, fink or MacPorts) yes (.deb or .rpm) @@ -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. @@ -1221,9 +1221,9 @@ git 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 +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 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 `_. .. _Review Board: http://www.review-board.org/ @@ -1284,14 +1284,14 @@ git git-svn_ All three DVCSs have svn support, although git is the only one to come with that support out-of-the-box. - + Server Support ============== ==== ================== DVCS Web page interface ----- ------------------ +---- ------------------ bzr loggerhead_ hg hgweb_ git gitweb_ @@ -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. @@ -1367,19 +1367,19 @@ Barrier to Entry The amount of time and effort it takes to get a checkout of Python's repository is critical. If the difficulty or time is too great then a person wishing to contribute to Python may very well give up. That -cannot be allowed to happen. +cannot be allowed to happen. I measured the checking out of code as if I was a non-core 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:: @@ -1476,7 +1476,7 @@ XXX import random print(random.choice(['svn', 'bzr', 'hg', 'git'])) - + Transition Plan ===============