I've updated the text of the ContributingCode page to hopefully get a better process for making patches visible and getting them reviewed and accepted faster.
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 [17]CopyrightAssignment.
For help getting the Upstart source, see [18]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 [19]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 [20]ChangeLog entry
Your patch should be mailed to the [21]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
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 [22]ChangeLog entry
Your patches should be mailed to the [23]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
[24]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 [email protected]
For more bzr with Launchpad tricks, see [25]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.
I also updated the CompilingUpstart and CopyrightAssignment pages.
Scott
--
Have you ever, ever felt like this?
Had strange things happen? Are you going round the twist?
signature.asc
Description: This is a digitally signed message part
-- upstart-devel mailing list [email protected] Modify settings or unsubscribe at: https://lists.ubuntu.com/mailman/listinfo/upstart-devel
