How To Forward-Merge Your Change After Your Pull Request Is Accepted Into Python 3.5.0rcX
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-merge3: 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 push11: 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-b...
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/
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-b...
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.)
participants (2)
-
Larry Hastings -
Terry Reedy