[Python-Dev] How To Forward-Merge Your Change After Your Pull Request Is Accepted Into Python 3.5.0rcX

[Larry Hastings]

Now that we're in the "release candidate" phase of Python 3.5.0, the 
workflow
has changed a little.  We're trying an experiment using Bitbucket and pull
requests.  You can read about that workflow, here:

https://mail.python.org/pipermail/python-dev/2015-August/141167.html

But the instructions for that workflow are pretty hazy on what you do after
your pull request is accepted.  This message is an addendum to those
instructions, describing exactly what you should do after your pull
request is accepted.

To save wear and tear on my hands (and your eyes), for the rest of these
instructions, I'm going to refer to each place-you-can-check-things-in-to
by version number as follows:

         3.4   : hg.python.org/cpython (branch "3.4")
         3.5.0 : https://bitbucket.org/larry/cpython350 (branch "3.5")
         3.5.1 : hg.python.org/cpython (branch "3.5")
         3.6   : hg.python.org/cpython (branch "default")

With that nomenclature established I can now precisely say: when your pull
request is accepted into 3.5.0, you need to merge from 3.5.0 into 3.5.1,
and then from 3.5.1 into 3.6.

Doing this is much like the existing workflow.   You use "hg merge" to merge
your changes from previous versions into subsequent versions (what I call
"forward merging").

What complicates matters is the fact that the 3.5.0 release candidates don't
live in the normal repo--they lives in a repo on Bitbucket which is only
writeable by me.  In order to keep a tight lid on the changes checked in to
the 3.5.0 release candidates, I won't pull revisions from the normal CPython
repo.  (If I did, I'd also pull in changes intended for 3.5.1, and...
it'd be a mess.)

So here come the instructions.  They look long, but that's just because I go
into a lot of detail to try and make them as foolproof as possible. They
aren't really much longer or more complicated than the steps you already
follow to perform forward-merges.

Note that these are easy, guaranteed-clean instructions on how to 
perform the
merge.  Are there shortcuts you could take that might speed things up?  Yes.
But I encourage you to skip those shortcuts and stick to my instructions.
Working with multiple branches is complicated enough, and this external repo
makes things even more complicated.  It's all too easy to make a mistake.


HOW TO FORWARD-MERGE FROM 3.5.0 TO 3.5.1
----------------------------------------


  1: Wait until your pull request has been accepted.


  2: Make a *clean* local clone of the CPython tree, updated to the "3.5"
     branch.  In my instructions I'll call the clone "cpython351-merge":

         % hg clone ssh://hg@hg.python.org/cpython -u 3.5 cpython351-merge

         % cd cpython351-merge


  3: Confirm that you're in the correct branch.  You should be in the
     "3.5" branch.  Run this command:

         % hg id

     Let's assume that the current head in the "3.5" branch has changeset
     ID "7890abcdef".  If that were true, the output of "hg id" would look
     like this:

         7890abcdef (3.5)

     It might also say "tip" on the end, like this:

         7890abcdef (3.5) tip

     If it doesn't say "3.5", switch to the 3.5 branch:

         % hg up -r 3.5

     and repeat this step.


  4: Pull from the 3.5.0 repo into your "cpython351-merge" directory.

         % hg pull ssh://hg@bitbucket.org/larry/cpython350

     You should now have two "heads" in the 3.5 branch; the existing head
     you saw in the previous step, and the new head you just pulled in,
     which should be the changeset from your pull request.


  5: As an optional step: confirm you have the correct two heads.
     This command will print a list of all the heads in the current repo:

         % hg heads

     Again, you should have exactly two identified as being on the "3.5"
     branch; one should have the changeset ID shown by "hg id" in step 3,
     the other should be your change from the pull request.


  6: Merge the two heads together:

         % hg merge

     If there are merge conflicts, Mercurial will guide you through the
     conflict resolution process as normal.


  7: Make sure that all your changes merged properly and you didn't
     merge anything else by accident.  I run these two commands:

         % hg stat

         % hg diff

     and read all the output.


  8: Make sure Misc/NEWS has your update in the right spot.  (See below.)


  9: Check in.  The checkin comment should be something like

         Merge from 3.5.0 to 3.5.1.


10: Push your changes back into the main CPython repo.

         % hg push


11: Now forward-merge your change to 3.6 as normal, following the
     CPython Dev Guide instructions:

https://docs.python.org/devguide/committing.html#merging-between-different-branches-within-the-same-major-version


FREQUENTLY ASKED QUESTIONS
--------------------------


Q: I screwed something up!  What do I do now?

If you haven't pushed your changes out, it's no problem.  Just delete your
repo and start over.

If you *have* pushed your changes out, obviously we'll need to fix the
mistake.  If you're not sure how to fix the problem, I suggest logging
in to the #python-dev IRC channel and asking for help.


Q: What do I need to do about Misc/NEWS?

I'm glad you asked!

First, you *must* put your Misc/NEWS update into the correct section.  If
you're creating a pull request for Python 3.5.0 rc-something, put it in the
3.5.0 rc-something section.  If you're checking in to 3.5.1, put it in the
3.5.1 section.  If you're just checking into 3.6, put it in the 3.6.0 
alpha 1
section.

Second, when you merge forward, make sure the merge tool puts your Misc/NEWS
entry in the right section.  The merge tool I seem to use isn't particularly
smart about this, so I've had to manually edit Misc/NEWS many times to fix
it.  (When I released 3.5.0rc2, I had to do a lot of cleanup on Misc/NEWS,
and again in the 3.5.1 branch, and again in 3.6.)  Every time you merge
forward, make sure your Misc/NEWS entry is in the right spot.


Q: What if a second pull request is accepted before I get around to doing
the merge?

Well, *someone* needs to merge, and they're going to have to merge *both*
changes.  I can't come up with a good general policy here. Hopefully this
won't happen often; for now let's just handle it on a case-by-case basis.


Q: What if I have a bugfix for 3.4 that I want to ship with 3.5.0?

You have to check in twice, and merge-forward twice.  First, check in to 
3.4,
then merge forward into 3.5.1 and 3.6.  Then, once your pull request is
accepted into 3.5.0, do a "null merge" (a merge where no files are changed)
from 3.5.0 into 3.5.1 and 3.6.


Q: What if my pull request is turned down?

If your bug fix isn't critical enough to merit shipping with 3.5.0, just 
check
it into the normal 3.5 branch on hg.python.org and it'll ship with 3.5.1.
(And, naturally, forward-merge it into 3.6.)


//arry/
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.python.org/pipermail/python-dev/attachments/20150827/4f45085f/attachment.html>