Contributing Code to the SableCC Project

The page outlines some guidelines to help you contribute code to the SableCC project.

Mercurial Configuration

Contributions to the SableCC project are made by attaching Mercurial bundles to tickets. Therefore, you need to install and configure the Mercurial software appropriately.

You will find all the required information for installing Mercurial in the DevelopmentEnvironment page.

If you already have a recent version of Mercurial installed on your system, then you should copy the following text into your ~/.hgrc Mercurial configuration file to set up your name and email, and to get expressive git patches when you execute hg diff and similar commands :

[ui]
username = Your Name <your@address>

[defaults]
diff = --git
email = --git
export = --git

Step 1: Get a Clean Official Repository Clone

It is important that you get a new, clean clone of the official repository for each new code contribution, otherwise, the bundle you prepare in step 3 will likely include unrelated changes.

Here is how you get a local copy of the official repository:

$ hg clone http://sablecc.org/repository/sablecc.org mychange
$ cd mychange

Step 2: Write the Code

Once you have a clean repository clone, you can start developing new code. It is recommended that you save your code often.

Here is how you save your code:

$ hg ci

It is also recommended that you regularly update your code with the latest changes in the official repository.

Here is how you update your code with the latest changes in the official repository:

$ hg ci
$ hg pull
$ hg up  # or hg merge

Step 3: Prepare a Mercurial Bundle

Here is how you prepare a bundle containing the differences between your working code and the official repository :

$ # First, make sure everything is saved and up to date with the official repository
$
$ hg ci
$ hg pull
$ hg up
$
$ # Prepare the bundle
$
$ hg bundle mychange.bundle

This procedure assumes that:

• You were working on the tip revision of your repository when you executed the commands.
• Your repository was dedicated to implementing a single change and keeping your work in progress up to date with the official repository.

If your repository contains unrelated work, you should restart at step 1 to create a new clean repository clone, then migrate into it only the relevant revisions. This might be simple or not, depending on your familiarity with Mercurial. It is much simpler not to have to do this, so it is a good idea to always start with fresh repository clone for every change you plan to contribute to the SableCC project.

Step 4: Submit the Bundle

Finally, you submit your bundle to the project by attaching it to a ticket.

If your bundle fixes a bug which is already reported in a ticket, you attach your bundle to this ticket.

If your bundle is a new piece of code, you create a new ticket that describes your work, then you attach your bundle to it.