diff --git a/committing.rst b/committing.rst --- a/committing.rst +++ b/committing.rst @@ -273,81 +273,11 @@ ported without any modifications. -Porting Within a Major Version -'''''''''''''''''''''''''''''' - -Assume that Python 3.3 is the current in-development version of Python and that -you have a patch that should also be applied to Python 3.2. To properly port -the patch to both versions of Python, you should first apply the patch to -Python 3.2:: - - hg update 3.2 - hg import --no-commit patch.diff - # Compile; run the test suite - hg commit - -With the patch now committed, you want to merge the patch up into Python 3.3. -This should be done *before* pushing your changes to hg.python.org, so that -the branches are in sync on the public repository. Assuming you are doing -all of your work in a single clone, do:: - - hg update default - hg merge 3.2 - # Fix any conflicts; compile; run the test suite - hg commit - -.. note:: - *If the patch shouldn't be ported* from Python 3.2 to Python 3.3, you must - also make it explicit: merge the changes but revert them before committing:: - - hg update default - hg merge 3.2 - hg revert -ar default - hg commit - - This is necessary so that the merge gets recorded; otherwise, somebody - else will have to make a decision about your patch when they try to merge. - -When you have finished your porting work (you can port several patches one -after another in your local repository), you can push **all** outstanding -changesets to hg.python.org:: - - hg push - -This will push changes in both the Python 3.2 and Python 3.3 branches to -hg.python.org. - - -Porting Between Major Versions -'''''''''''''''''''''''''''''' - -Let's say you have committed your changes as changeset ``a7df1a869e4a`` -in the 3.2 branch and now want to port it to 2.7. This is simple using -the "graft" command, which uses Mercurial's merge functionality to -cherry-pick:: - - hg update 2.7 - hg graft a7df1a869e4a - # Compile; run the test suite - -Graft always commits automatically, except in case of conflicts, when you -have to resolve them and run ``hg graft --continue`` afterwards. - -Another method is using "export" and "import": this has the advantage that -you can run the test suite before committing, but the disadvantage that -in case of conflicts, you will only get ``.rej`` files, not inline merge -markers. :: - - hg update 2.7 - hg export a7df1a869e4a | hg import --no-commit - - # Compile; run the test suite - hg commit - - Using several working copies '''''''''''''''''''''''''''' -If you often work on bug fixes, you may want to avoid switching branches +It is possible to work on CPython with a single repository clone, but +if you often work on bug fixes, you may want to avoid switching branches in your local repository. The reason is that rebuilding takes time when many files are updated. Instead, it is desirable to use a separate working copy for each maintenance branch. @@ -359,8 +289,7 @@ $ hg clone ssh://hg@hg.python.org/cpython py3k -* Then clone it to create another local repository which is then used to - checkout branch 3.2:: +* Then clone it to create another local repository for the 3.2 branch:: $ hg clone py3k py3.2 $ cd py3.2 @@ -374,9 +303,10 @@ * You can also clone a 2.7-dedicated repository from the ``py3k`` branch:: - $ hg clone py3k py2.7 - $ cd py2.7 - $ hg update 2.7 + $ hg clone py3k py2.7 -u 2.7 + + (this command is equivalent to those used to create a local 3.2 branch, but + it's more concise.) Given this arrangement of local repositories, pushing from the ``py3.1`` repository will update the ``py3.2`` repository, where you can then merge your @@ -407,6 +337,82 @@ never modified locally. +Porting Within a Major Version +'''''''''''''''''''''''''''''' + +Assume that Python 3.3 is the current in-development version of Python and that +you have a patch that should also be applied to Python 3.2. To properly port +the patch to both versions of Python, you should first apply the patch to +Python 3.2:: + + cd py3.2 + hg import --no-commit patch.diff + # Compile; run the test suite + hg commit + +With the patch now committed, you want to merge the patch up into Python 3.3. +This should be done *before* pushing your changes to hg.python.org, so that +the branches are in sync on the public repository. Assuming all your clones +are in the same directory:: + + cd ../py3k + hg pull -u ../py3.2 + hg merge 3.2 + # Fix any conflicts; compile; run the test suite + hg commit + +.. note:: + *If the patch shouldn't be ported* from Python 3.2 to Python 3.3, you must + also make it explicit: merge the changes but revert them before committing:: + + hg pull -u ../py3.2 + hg merge 3.2 + hg revert -ar default + hg commit + + This is necessary so that the merge gets recorded; otherwise, somebody + else will have to make a decision about your patch when they try to merge. + +When you have finished your porting work (you can port several patches one +after another in your local repository), you can push **all** outstanding +changesets to hg.python.org:: + + hg push + +This will push changes in both the Python 3.2 and Python 3.3 branches to +hg.python.org. + + +Porting Between Major Versions +'''''''''''''''''''''''''''''' + +Let's say you have committed your changes as changeset ``a7df1a869e4a`` +in the 3.2 branch and now want to port it to 2.7. This is simple using +the "graft" command, which uses Mercurial's merge functionality to +cherry-pick:: + + cd py2.7 + hg pull -u + hg graft a7df1a869e4a + # Compile; run the test suite + +Graft always commits automatically, except in case of conflicts, when you +have to resolve them and run ``hg graft --continue`` afterwards. The import is +possible because changesets are unique per repository, and so in ``py2.7`` you +also have all of those of the other branches. + +Another method is using "export" and "import": this has the advantage that +you can run the test suite before committing, but the disadvantage that +in case of conflicts, you will only get ``.rej`` files, not inline merge +markers. :: + + cd py2.7 + hg pull -u + hg export a7df1a869e4a | hg import --no-commit - + # Compile; run the test suite + hg commit + + Differences with ``svnmerge`` '''''''''''''''''''''''''''''