The GenomeTools Contribution Process

GenomeTools development is centered around the GenomeTools development contract. If you contribute a nice patch which will be integrated into the master, we'll invite you to join the Maintainer's team and you can add "GenomeTools maintainer" to your resume or C.V.

This introductory text has been borrowed (with adjustments) from the ZeroMQ project.

Our process is this:

Log an issue that explains the problem you are solving or the feature you are adding.
Provide a test case if possible.
Make your change as a pull request (see below).
Discuss on the issue page or the gt-dev mailing list as needed.
Close the issue when your pull request is merged and the test case passes.

Getting Started

Download and install git. On Ubuntu or Debian, you can use the following command:

apt-get install git

If you are new to git, read the git docs, and Pro git by Scott Chacon.

Ensure that your copy of git is configured with your real name and the e-mail address you wish to be associated with your contributions. This is required to correctly track authorship:

$ git config --global user.name "Your Name"
$ git config --global user.email your.name@example.com

Create a user profile at GitHub with your real name and the same email you used to configure your git.

Basic Techniques

If you're new to git, especially if you come from SVN, you work by getting full copies of the repository on your local hard disk, and then exchanging sets of changes to and from other gits. It sounds complex, and sometimes is, but it works very well for large loose groups like ours.

In git, you work with a set of 'branches', starting with the 'master' branch. Use 'git branch' to see what branches you have. To get a git repository onto your hard disk use the 'git clone' command, e.g.:

$ git clone git://github.com/MyName/genometools.git

Behind a firewall you may need to use 'http:' instead of 'git:'.

Your clone has an origin, which is a 'remote' by that name. Use 'git remote -v' to see what remotes you have.

To make your changes: use your favorite tools to edit, compile, build, test. Do not allow your editor to reformat code you're not changing, or remove whitespaces elsewhere, this will make your patches useless.

To commit your work: use 'git add (files)' and 'git commit'. Use 'git commit —amend' to add to or fix up the previous commit.

The 'git commit' command opens an editor for you to enter a commit message. Provide a short one-line summary, followed by a blank line, followed by a description of what you changed. The commit message becomes part of the permanent history of the project if your changes are accepted, so be clear and concise.

To abandon your changes: either wipe your directory and re-clone the project git, or use the 'git reset' command. All git commands have help ('git reset —help'), and extensive explanation online.

To push a branch to a remote: 'git push <remotename> <branchname>', usually 'git push origin master'.

To pull a branch from a remote: 'git pull origin master', which fetches the master branch from the origin remote, and merges it into your local master branch.

The Pull Request Model

The home page for the GenomeTools git repository has a button "Fork", which will fork the project into your own profile. Click it, and you get a fork of the project git. Clone your forked git to your hard disk. You can now work in your forked git.

The best strategy is to make each change (a set of commits) in its own branch. Your master branch can then track precisely the original repository master.

Work and commit your work as explained in Basic Techniques, and push your changed branches back to your forked repository. When you're ready to send your work to the project owner, go to github.com and click the "pull request" button. Do make one pull request for each set of changes that go together.

To resync your fork with the original repository, add a remote that points to that repo, and use 'git pull —rebase remotename master'. For example:

#  One time when you start working
git remote add gt-master git://github.com/genometools/genometools.git
#  Each time you need to resync
git pull --rebase gt-master master

Separate Your Changes

Separate different independent logical changes into separate commits (and thus separate patch submissions) when at all possible. This allows each change to be considered on it's own merits. Also, it is easier to review a batch of independent changes rather than one large patch.

Write Good Commit Messages

Commit messages become the public record of your changes, as such it's important that they be well-written. The basic format of git commit messages is:

A single summary line. This should be short — no more than 70 characters or so, since it can be used as the e-mail subject when submitting your patch and also for generating patch file names by 'git format-patch'. If your change only touches a single file or subsystem you may wish to prefix the summary with the file or subsystem name.
A blank line.
A detailed description of your change. Where possible, write in the present tense, e.g. "Add assertions to zmq_foo()". If your changes have not resulted from previous discussion on the mailing list you may also wish to include brief rationale on your change. Your description should be formatted as plain text with each line not exceeding 80 characters.

Give Yourself Credit

Add yourself to the CONTRIBUTORS file with your commit. The maintainers won't do this, it's your choice whether you consider your patch worth a mention, or not. Note that you must make contributions under your real name, associated with your github account.

Copyrights and Licenses

Make sure your contributions do not include code from projects with incompatible licenses. GenomeTools uses the ISC license. If your code isn't compatible with this, it will sooner or later be spotted and removed. The best way to avoid any license issues is to write your own code.