[Python-Dev] Instructions on the new "push request" workflow for 3.5.0rc1+ through 3.5.0 final

[Larry Hastings]

As of Python 3.5.0rc1, the canonical repository for Python 3.5.0 is
*no longer* on hg.python.org.  Instead, it's hosted on Bitbucket on
my personal account, here:

     https://bitbucket.org/larry/cpython350

Since 3.5.0rc1 isn't out yet I'm keeping the repository private for now.
Once 3.5.0 rc1 is released (hopefully Monday) I'll flip the switch and make
the repository public.  (I'll email python-dev and python-committers when
that happens.)


Putting it succinctly, here's a table of versions and where you'd check in
for your change to go there:

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

You'll notice nobody but myself has checkin permissions for my 3.5.0 repo on
Bitbucket.  That's on purpose.  The only way you can get changes in to 3.5.0
now is by sending me a Bitbucket "pull request".  This is a workflow
experiment, to see if we as a community like this sort of new-fangled gizmo.

For now, we're only using Bitbucket for the actual final checking-in stage.
Requests for fixes to be accepted into 3.5.0 and code review will all still
happen on the Python issue tracker.

Also, I'm officially now asking you folks to do the forward-merge into 3.5.1
and 3.6.0 yourselves.


Here's how to get a fix checked in for 3.5.0, starting with 3.5.0rc1+ and
continuing through until 3.5.0 final.

Pre-requisites:
   * You must have a Bitbucket account.
   * You must have commit rights to the CPython repository.

  1. Create an issue on the Python issue tracker for the problem.

  2. Submit a patch that fixes the problem.

  3. Add me to the issue and get me to agree that it needs fixing in 3.5.0.
     (You can attempt this step before 2 if you prefer.)

  4. Fork my repository into your Bitbucket account using their web GUI.
     To do that, go to Bitbucket, log in, then go to my 3.5.0 repo:

     https://bitbucket.org/larry/cpython350

     and press the "Fork" link in the left column.  Bitbucket has a tutorial
     on how to do this, here:

https://confluence.atlassian.com/display/BITBUCKET/Fork+a+teammate%27s+repository

     Note: DO NOT start with a conventional CPython trunk cloned from
     hg.python.org.  The 3.5 branch in my repo and the 3.5 branch in normal
     CPython trunk have intentionally diverged and *need* to stay 
out-of-sync.

  5. Make a local clone of your fork on your computer.

     Bitbucket has a tutorial on how to do that, here:

https://confluence.atlassian.com/display/BITBUCKET/Copy+your+Mercurial+repository+and+add+source+files

     Reminder: switch to the 3.5 branch!

  6. Apply your change to the 3.5 branch and check in.

     Reminder: check in to the 3.5 branch!

  7. Make sure you checked in your change to the 3.5 branch.

     Reminder: Seriously.  I keep messing this up.  I say, the more 
reminders,
     the better.

  8. Push your change back to *your* fork on *your* Bitbucket account.

     Just normal "hg push" should work here.

     In case it helps, I recommend using the "https" protocol for this 
step, as
     it sidesteps ssh authentication and prompts you for your Bitbucket 
username
     and password.

  9. Create a pull request using Bitbucket's web GUI.

     Bitbucket has a tutorial on how to create a pull request, here:

https://confluence.atlassian.com/display/BITBUCKET/Create+a+pull+request

     On the "Create pull request" web GUI, make sure that you specify
     branch "3.5" for *both* your repo *and* my repo.  Also, make sure
     you *don't* check the "Close 3.5 after the pull request is merged"
     check box.

     (If you use the "Compare" page, you also need to select "3.5" in both
     drop-down lists--one for my repo, and one for yours.)

10. Paste a link to the pull request into the issue tracker issue for this
     change request.

11. Wait for confirmation that I've accepted your pull request into the
     3.5.0 repo.

12. Pull your accepted change from your local Bitbucket fork repo into
     a normal hg.cpython.org CPython repo, merge into 3.5, then merge
     into 3.6, then push.


For the record, here's what *my* workflow looks like when I accept your
pull request:

1. Click on the URL you pasted into the pull request.

2. Visually check that the diff matches the approved diff in the issue
    on the issue tracker.

3. Click on the "Merge" button.


Frequently Asked Questions
==========================

Q: What if someone sends me a "pull request" for a change that doesn't
    merge cleanly?
A: Then I'll decline it, and ask you on the issue tracker to rebase
    and resubmit.

Q: What if someone sends me a "pull request" but they don't have commit
    rights to CPython?
A: I'll ignore it.  I'll only pay attention to pull requests pasted into
    the issue tracker by someone with commit rights.

Q: Whose name goes on the commit?
A: It gets the name the checkin was made with.  Don't worry, your name
    will stay on your commit.

Q: This seems like a lot more work than the old way.
A: For you guys, yes.  But notice how little work it is for *me*! Seriously.

Q: Can I reuse my fork / my local copy?  Or do I have to create
    a fresh one each time?
A: I don't care either way.  All I care about are clean pull requests.
    If you're careful you should have no trouble reusing forks and local
    checkouts.  If it were me, I'd probably use a fresh fork each time.
    Forks are cheap and this way is cleaner.


I'll add these instructions to the Python Dev Guide in the next day or two.


/arry

p.s. Remember to use the 3.5 branch!