Contributing code to any Open Source project for the first time can be an exciting, but also nerve-wracking, thing. Each project has its own quirks, personalities and procedures and you need a crash-course in navigating them to get your patch in. This wiki page attempts to be that course for Upstart.

All contributions need to undergo CopyrightAssignment.

For help getting the Upstart source, see CompilingUpstart.

Contributions tend to come in two forms: bug fixes and features. We'll address each individually.

Bug Fixes

Bug fixes fix bugs. There are a few simple rules you should follow to make sure your fix is accepted quickly and without issue.

  1. Make sure the bug is open against the Upstart project [ on Launchpad]

  2. Make sure your commit/patch only fixes the bug and does not introduce other unnecessary changes. If you need to do so, split your commit/patch up into multiple ones for separate submission.
  3. Make sure your code matches the coding style (see the HACKING file in the top-level of the source).
  4. Include one or more test cases. These should fail before the rest of the change is applied (it's ok for fail to be a failure to compile, or a valgrind failure) and succeed after the full change is applied.
  5. Include a correctly formatted ChangeLog entry

Your patch should be mailed to the [ upstart-devel mailing list] with the subject line beginning with "[PATCH]". If your patch is for 0.3.x or 0.5.x include the version in the subject line.


Features are new work to Upstart, they should be kept separate from simple bug fixes. Just like bug fixes, there are some golden rules to follow.

  1. Discuss your idea on the mailing list first. A feature patch submitted after consensus has been reached in a discussion is far more likely to be accepted than one out of the blue. Use the Wiki to help draft your feature, write a specification if that helps, etc.
  2. Split your commits/patches up where possible to make the merging process easier. A line of related patches also helps to locate problems later down the line compared to a single large patch.
  3. Make sure your code matches the coding style (see the HACKING file in the top-level of the source).
  4. Include test cases to cover all of your new code. Use the --enable-compiler-coverage configure argument and gcov to make sure.

  5. Make sure that all existing test cases pass too, it's ok if they need changing because you've updated API or changed output.
  6. Include a correctly formatted ChangeLog entry

Your patches should be mailed to the [ upstart-devel mailing list] as replies to a covering letter describing the feature. The subject line for each patch should begin with "[PATCH xx/yy]" giving the patch number in series and the total number.

Features are generally not accepted for the 0.3 or 0.5 series.

Working with bzr

Since bzr is a distributed revision control system, your local copy is also a branch that you can work on and commit to. There are two common styles for patch submission by revision control.

Per-bug or feature branch

Simply create a new branch for each bug fix, or each new feature. You can then work in this branch to get the change right before submission.

For bug fixes, when you're ready to commit your patch to your branch, use the --fixes option to bzr to record the bug fix:

$ bzr commit --fixes lp:1234

You can push these to Launchpad so that they are visible to everybody.

$ bzr push lp:~YOURUSERNAME/upstart/bugNNNNNN

$ bzr push lp:~YOURUSERNAME/upstart/make-everything-blue

A single commit per bug fix is preferred, with the commit including all code changes and the test case, with an appropriately formatted ChangeLog message (this will be the commit message to the master branch when merged). Sometimes it's useful to be able to make temporary commits and then rewind to make the final commit. One way to remove your temporary commits so you can make the proper commit to be pushed and merged is:

$ bzr uncommit -r submit:

This leaves your changes in the working tree, but removes the commit logs for them.

You should make sure that you're new branch is linked to the bug (the commit command above should do this for you), and you should propose your branch for merging into the mainline. Both of these actions may be performed from the Launchpad web interface for the branch.

For new features, multiple commits are also still preferred as are multiple patches.

While everything is linked up, you should still mail your patch to the mailing list for review. Make sure you include your branch URL so it's known to be on Launchpad. The easiest way to do this is

$ bzr send

For more bzr with Launchpad tricks, see [ Using Bazaar with Launchpad].

Submission branch

If you're doing lots of different fixes of features, sometimes it's more appropriate to have a single branch of patches queued for merging. The usual name for this branch is for-keybuk.

You'll want to use the rebase bzr plugin to make sure that your branch is always just the commits you want merged on top of the current trunk.

This is considered an advanced approach for experts only.

-- CategoryDoc

ContributingCode (last edited 2009-06-15 09:57:19 by scott)