Please note:The SCons wiki is now restored from the attack in March 2013. All old passwords have been invalidated. Please reset your password if you have an account. If you note missing pages, please report them to webmaster@scons.org. Also, new account creation is currently disabled due to an ongoing spam flood (2013/08/27).

Mercurial (Hg) Workflows for working with SCons

Repository is at https://bitbucket.org/scons/scons .You will need to create a free account.

Default branch is where current development is done; branches are for fixes to existing releases.

Anyone can fork the repo on the Bitbucket site, clone it on their own computer and make modifications.

If you have a patch which follows the submission guidelines (code, doc, test) you can submit a pull request at bitbucket.

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 trunk into a release branch, or you'll get everything.

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 (hg) is, uhh, The Definitive Guide.

To fork the repo go to https://bitbucket.org/scons/scons, log on to bitbucket, 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.

Once you clone your fork of the repo, you should add the following as .hg/hgrc in the base dir of your clone:

[paths]
default = ssh://hg@bitbucket.org/<my_user>/<my_fork_name>
upstream = ssh://hg@bitbucket.org/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 scons's repository via:

hg update -C default
hg pull upstream
hg update

Then to work on a bug or feature the simplest thing is to work directly on the default branch. Feature branches are not usually needed except for long-term development, but you're welcome to work that way if you like. You can just make your changes (including doc and tests); when you're happy, commit them, and push:

<do work>
hg addremove
or
hg add <each file individually>
hg commit -m "useful comment on checkin purpose"
hg push -f

Then goto bitbucket.org/<user>/<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.

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

For SCons admin, how to accept pull requests:

You can see the diffs on the bitbucket.org website. When you do that it will give you the hg commands to pull the user's repo to run tests on. You can then either use hg to push those changes to scons repo on bitbucket, or do it on the website. If the user was working on the default branch, the following should suffice:

hg pull https://bitbucket.org/USER/scons -r 123abc456  # only pull the rev corresponding to the pull request, or you might get other things that user is working on.
hg heads # see what we got
hg merge # with no args, merge merges the user's head into the tip.  It does not commit.
# run tests, make changes as needed, update src/CHANGES.txt
hg commit -m 'Merged in USER/scons (pull request #22), fixes #1234 (segfault on startup due to too many unicorns)
# (note: use exact format of above merge message at least up to the comma -- bitbucket makes various parts into links.)
hg push # that's it -- bitbucket will figure out that this accepts the pull request, you don't need to do anything special.

If the user was working on a feature branch, it's a little more complicated. Here's what I did to accept a pull request on the "issue2812" branch. I started in my clone of the master SCons repo, on the default branch.

hg pull https://bitbucket.org/USER/scons # pulls all his branches -- probably could have just pulled issue2812?
hg heads # see what we got
hg merge issue2812 # merge in his branch
# run tests, make any other needed changes here
hg push --new-branch -b default # --new-branch needed here because this push creates issue2812 branch in master repo
# now close the branch:
hg update issue2812
hg commit --close-branch -m'Closing issue2812 branch; accepted.'
hg push -b issue2812

SconsMercurialWorkflows (last edited 2012-05-27 16:25:51 by GaryOberbrunner)