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