Forking and merging on bitbucket

For some recent work I was doing with Satchmo's Fedex module, I decided to go through the process of forking on bitbucket with the eventual goal of merging this back into Satchmo tip. Over time, I've had many folks try to fork Satchmo and issue pull request back to bitbucket but some people end up with a bit of a tangled mess.


Here are the steps I used to fork Satchmo, make changes to my new fork and merge changes from tip back into my working fork. That last portion is key, everyone's life is much easier if you frequently merge your fork with the latest Satchmo changes.

Your first step is to fork satchmo, by clicking the fork icon in bitbucket. When you do this, you have an option to name the fork as well as make it private, etc. If you plan to get your changes pulled back into tip, don't make it private. I also encourage you to come up with a somewhat distinctive name and create a meaningful description. I'd also recommend that you fork from tip. I can't think of a good reason why you would choose another tagged version.

Bitbucket will do its magic behind the scenes and create your fork. When it's done, you'll go to your fork's overview page. From here it will show you how to pull down your fork. In my instance:

hg clone ssh://[email protected]/chris1610/satchmo-fedex

From here on, make changes, add and remove files and do hg commits and pushes on your code base.

The "secret" is to periodically merge in with satchmo tip. From your local fork:

hg pull -r default
hg update
hg merge
hg commit
hg push

If you frequently pull in any recent changes from Satchmo into your fork and merge it appropriately, you'll end up with a much simpler process of getting it pulled back into satchmo tip.

Once you've completed all your changes and want me to pull it back into satchmo, click on the "send pull request" button to send a request and I will get notified of the pull and be able to see a really clean diff of all your changes. If the pull request is complex, it's probably best to create a ticket first so the community can comment on the issue.

I hope this clarifies the process a bit and encourages folks to use this really useful feature to submit changes to satchmo.

Posted on November 28, 2011 by chris django hg satchmo


Reply to original: