Jetty/Contributor/Contributing Patches

How to contribute a patch to Jetty @ Eclipse.

Git Diff

The simplest way to contribute a patch is to make a modification to a cloned copy of jetty and then generate a diff between the two versions.

From the top level of the cloned project:

git diff > ######.patch

The hash marks should be the bugzilla issue that you will be attaching the issue to. All patches coming into jetty @ eclipse much come in through bugzilla for IP tracking purposes. Depending on the size of the patch the patch itself may be flagged as +iplog where it is subject to lawyer review and inclusion with our iplog from here to eternity. We are sorry we are unable to apply patches that we receive via email. So if you have the bugzilla issue created already just attach the issue and feel free to bug us on IRC to take a look. If there is no bugzilla issue yet, create one, make sure the patch is named appropriately and attach it.

When the developer reviews the patch and goes to apply it they will use:

git apply < ######.patch

If you want to be a nice person, test your patch on a clean clone to ensure that it applies cleanly. Nothing frustrated a developer quite like a patch that doesn't apply.

Git Format Patch

Another approach if you want your name in shiny lights in our commit logs is to use the format patch option. With this approach you commit into your cloned copy of jetty and use the git format patch option to generate what looks like an email message containing all of the commit information. This applies as a commit directly when we apply it so it should be obvious that as with the normal diff we much accept these sorts of patching only via bugzilla.

From the top level of the cloned project:

Make your changes and commit them locally using git commit. Then use git log to identify the commit(s) you want to include in your patch:

commit 70e29326fe904675f772b88a67128c0b3529565e
Author: Thomas Becker <tbecker AT intalio . com>
Date:   Tue Aug 2 14:36:50 2011 +0200

   353563: HttpDestinationQueueTest too slow

Use git format-patch to create the patch:

git format-patch -1 70e29326fe904675f772b88a67128c0b3529565e > ######.patch

You can also include multiple commits in one patch file. See http://www.kernel.org/pub/software/scm/git/docs/git-format-patch.html for details.

When a developer goes to apply this sort of patch then we must assume responsibility for applying it to our codebase from the IP perspective. So we much be comfortable with the providence of the patch and that it is clear of potential issues. This is not like a diff where you get to edit it and clean up issues before it get applied. The commit is recorded locally and the developer will then have a chance to make additional commits to address any lingering issues.

To apply the patch the developer will use a command like:

git am -s < ######.patch

Providing it applies cleanly there will now be a commit in their local copy and they can either make additional commits or push it out. The '-s' option attaches a 'Signed By: ' line to the commit with the developers commit information. This is required, without it the commit should be rejected by the eclipse git server as not valid. There is an update hook in place that validates that either the commit or signed by fields are in fact eclipse committers authorized to commit to the repository.