Contributing Code to the SableCC Project

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

Mercurial to Git Migration

IMPORTANT: SableCC has recently migrated its source code repository from Mercurial to Git. To get a copy of the repository, type:

git clone http://sablecc.org/sablecc.git

This page will soon be updated to reflect this change.

Useful Command-Line Options

With many git commands, it is highly recommended to add the options

  -M -C --find-copies-harder --patience --pretty=fuller

This will allow git to

  1. detect file renames and copies (-M -C --find-copies-harder),
  2. show human-readable diffs (--patience), and
  3. provide both author and commiter information (--pretty=fuller).

For example, to see the content of the latest commit, you can type:

git show -M -C --find-copies-harder --patience --pretty=fuller HEAD

To see the difference between the head of repository copy and the official repository, you can type:

git diff -M -C --find-copies-harder --patience --pretty=fuller origin/master HEAD

To retrieve the origin/master hash, you can type:

git show origin/master --pretty=format:"commit %H" -s

(OBSOLETE) 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

When you add, rename/move, or delete a file, you must tell Mercurial about it:

$ hg add somenewfile.txt
$ hg mv oldname.txt newname.txt
$ hg del obsoletefile.txt
$
$ hg ci  # this saves the above changes.

To easily detect files that are not properly tracked by Mercurial (because you failed to svn add/rename/delete them), you can run the status command:

$ hg st
? someuntrackedfile.txt
! somemissingfile.txt

The status command will list modified, added, removed, deleted but still tracked, and not tracked files. Each file is preceded by a marker:

M = modified
A = added
R = removed
! = deleted, but still tracked
? = not tracked

A "deleted but still tracked file" usually indicates a forgotten hg del command. A "not tracked" file may indicate a forgotten hg add command.

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 :

$ # Check that there are no outstanding changes, and that everything is properly tracked by Mercurial
$ hg st
$
$ # Then, 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.