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

[Terry Reedy]

On 8/27/2015 3:32 PM, Larry Hastings wrote:
>
>
> 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

I am going to be making a pull request.  I presume that making a copy of 
my current master clone, freshly updated by a pull, should work just as 
well.

>   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.)

After all the steps above, which will take some time, refreshing the 
cpython351-merge clone would be a good idea, to minimize the chance of 
losing a push race.

hg pull ssh://hg@hg.python.org/cpython


>   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

I was under that impression that I should not push commits before 
merging forward, but I gather that this is actually ok as long as one 
quickly follows with a separate merge and 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

I presume this means first switching back to my normal 3.6 clone and 
pulling to get the 3.5 merge


> 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.

If a patch is a 3.4 bugfix to be null-merged (as below), you could say 
that in the commit message in case you accept another request before the 
null merge is taken care of.

> 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.)