diff --git a/committing.rst b/committing.rst --- a/committing.rst +++ b/committing.rst @@ -203,6 +203,90 @@ .. _eol extension: http://mercurial.selenic.com/wiki/EolExtension +Clones Setup +------------ + +There are several possible ways to set up your Mercurial clone(s). If you are +a core developer, you often need to work on the different branches, so the best +approach is to have a separate clone/directory for each active branch. If you +are a contributor, having a single clone might be enough. + +Single Clone Approach +''''''''''''''''''''' + +This approach has the advantage of being simpler because it requires a single +clone/directory, but, on the other hand, it requires you to recompile Python +every time you need to switch branch. For this reason, this approach is not +suggested to core developers, but it's usually suitable for contributors. + +See :ref:`checkout` to find information about cloning and switching branches. + +Multiple Clones Approach +'''''''''''''''''''''''' + +This approach requires you to keep a separate clone/directory for each active +branch, but, on the other hand, it doesn't require you to switch branches and +recompile Python, so it saves times while merging and testing a patch on the +different branches. For this reason, this approach is suggested to core +developers. + +The easiest way to do this is by using the `share extension`_, that can be +enabled by adding the following lines to your ``~/.hgrc``:: + + [extensions] + share = + +Once you have :ref:`cloned the hg.python.org/cpython repository ` +you can create the other shared clones using:: + + $ hg share cpython 2.7 # create a new shared clone + $ cd 2.7 # enter the directory + $ hg up 2.7 # switch to the 2.7 branch + +You can then repeat the same operation for the other active branches. +This will create different clones/directories that share the same history. +This means that once you commit or pull new changesets in one of the clones, +they will be immediately available in all the other clones (note however that +while you only need to use ``hg pull`` once, you still need to use ``hg up`` +in each clone to update its working copy). + +In order to apply a patch, commit and merge it on all the branches, you can do +as follow:: + + $ cd 2.7 + $ hg pull ssh://hg@hg.python.org/cpython + $ hg up + $ hg import --no-c http://bugs.python.org/url/to/the/patch.diff + $ # review, run tests, run `make patchcheck` + $ hg ci -m '#12345: fix some issue.' + $ # switch to 3.2 and port the changeset using `hg graft` + $ cd ../3.2 + $ hg up + $ hg graft 2.7 + $ # switch to 3.3, merge, and commit + $ cd ../3.3 + $ hg up + $ hg merge 3.2 + $ hg ci -m '#12345: merge with 3.2.' + $ # switch to 3.x, merge, commit, and push everything + $ cd ../3.x + $ hg up + $ hg merge 3.3 + $ hg ci -m '#12345: merge with 3.3.' + $ hg push ssh://hg@hg.python.org/cpython + +If you don't want to specify ssh://hg@hg.python.org/cpython every time, you +should add to the ``.hg/hgrc`` files of the clones:: + + [paths] + default = ssh://hg@hg.python.org/cpython + +Unless noted otherwise, the rest of the page will assume you are using the +multiple clone approach, and explain in more detail these basic steps. + +.. _share extension: http://mercurial.selenic.com/wiki/ShareExtension + + Handling Others' Code ---------------------