Mercurial Workflows for working with SCons
The main repository is at https://bitbucket.org/scons/scons .You will need to create a free account at Bitbucket.
- "Default" branch is where current development is done; named branches are for fixes to existing releases, and in some cases large features.
- Anyone can fork the repo on the Bitbucket site, clone it on their own computer and make modifications.
- Patches are reviewed and accepted by the release team.
- For point releases and fixes, apply the patch to the oldest supported release and merge forward always.
- Never merge the default branch into a release branch, or you'll get everything.
New to Mercurial?
A simple hg tutorial is at http://mercurial.selenic.com/wiki/Tutorial, with more detail at http://hginit.com/ (Joel Spolsky's longer intro to hg). The definitive guide to Mercurial is, uhh, The Definitive Guide.
Forking your personal copy
To fork the repo go to https://bitbucket.org/scons/scons, then click the "fork" button (a blue arrow). You will be asked to give the fork a name; please choose something that describes the work to be done.
Once you have the fork made, you will want to clone that fork on your own computer. Having Mercurial setup properly, you can call:
hg clone https://email@example.com/my_user/scons
and should now have a copy of the sources in the folder "scons" to work with.
Once you cloned your fork of the repo, you should add the following as .hg/hgrc in the base dir of your clone:
[paths] default = ssh://firstname.lastname@example.org/<my_user>/<my_fork_name> upstream = ssh://email@example.com/scons/scons
For this to work correctly, ensure that you added your public SSH key to your BitBucket account as described at https://bitbucket.org/help/UsingSSH/ (look out for the section Basic setup with a single default identity). Then you can pull updates from the "original" scons repository via:
hg update -C default hg pull upstream hg update default
Adding commits to the "default" branch
Then to work on a bug or feature, the usual thing is to work directly on the "default" branch. No named branches, please! You can just make your changes (including doc and tests); when you're happy, commit them, and push:
<do some work, and then add/remove files automatically with> hg addremove <or add files individually with> hg add <single file> <after having adding all new files, commit your changes with> hg commit -m "useful comment on checkin purpose" <push your local commits up to your fork repo with> hg push -f
Then goto "bitbucket.org/<my_user>/<my_fork_name>" and click "Pull request", select the "from" branch "default" (or your branch if you created one). Select the "default" branch as the "to" branch. Please type reasonably informative subject and description and "submit" the pull.
Working on several "branches" at once
If you need to organize your commits better, because you're actually working on several bugs at the same time, you can use the "bookmark" feature of Mercurial. This is pretty close to a "branch" in git. Before you start with new bugs, you'll want to mark the current tip revision of "default" as common ancestor, with something like:
hg bookmark -f origin
. Now you can add bookmarks for your bug or feature "branches" in the same place:
hg bookmark bug234 hg bookmark bug987
By updating to a bookmark
hg update -r bug987
you're "switching branches", and all following commits will go onto that current branch. Plus, you can update to your "origin" mark and add a new bookmark at any time.
You only have to be careful later, when creating a pull request. If you have pushed multiple bookmarks, you'll have several heads on the "default" branch to choose from. Be sure to pick the right commit for your pull request, by checking its revision number.
Updating a pull request
After you submitted your pull request, it gets reviewed by other developers. Chances are high that you receive comments or questions about your changes (see also the Developer Guide intro). In some cases you'll get asked to add or correct things, so you have to update your request.
For this, update your local "scons" copy to the corresponding bookmark, if required.
hg update -r <bookmark_name>
For the "default" branch, make sure that you're pointing to the last commit of your pull request. Then continue development by adding/changing files and committing them. Finally, push them up to your personal "scons" fork with
hg push -f
Now, go to the original "scons" repo page at bitbucket ( https://bitbucket.org/scons/scons ), and make sure that you're logged in. Go to your pull request, and then click "Edit" (right). Bitbucket should pick up your latest changes, and offer you to include their commits into the pull request.
Feature branches (named branches) are not usually needed, except for long-term development. If you really think you need one, please contact the developer team via one of the mailing lists first (scons-users or firstname.lastname@example.org), and ask for permission. The rest of the workflow is similar to the descriptions above.
Once the pull request has been accepted, only if you were working on a feature branch, do the following to mark that branch done. (Not needed if working on the "default" branch.)
hg branches hg up -C <reasonable_name_for_work_being_done> hg commit --close-branch -m "Done with this branch" hg up -C default hg push
Before working on the next bug/feature
If you have cycled through the sections above, your pull request should now be merged to the "default" branch of the mainline. Before you continue to work on the next bugfix or feature, it's a good idea to update the working copy of your personal fork with the latest commits to bitbucket.org/scons/scons.
So, do a:
hg update -C default hg pull upstream hg update default
, to ensure that your new changes and commits will be as close as possible to the mainline development. Thank you.
For SCons maintainers' side of the mercurial workflow, see DeveloperGuide/AcceptingPullRequests.