Jetty Logo
Version: 9.2.3.v20140905
Contact the core Jetty developers at www.webtide.com

private support for your internal/customer projects ... custom extensions and distributions ... versioned snapshots for indefinite support ... scalability guidance for your apps and Ajax/Comet projects ... development services from 1 day to full product delivery

Contributing Patches

Sign a CLA
Use Bugzilla
Git Diff
RECOMMENDED - Git Format Patch
Contributing with Gerrit
Contributing via GitHub PullRequests

How to contribute a patch to the jetty project. You should first familiarize yourself with the Eclipse wiki page on contributing via Git.

Sign a CLA

The Eclipse Foundation has a strong Intelectual Property policy which tracks contributions in detail to ensure that:

  1. Did the contributor author 100% of the content?

  2. Does the contributor have the rights to contribute this content to Eclipse?

  3. Is the contribution under the project’s license(s) (e.g. EPL)

Thus a contributor needs to e-sign a Contributor Licence Agreement (for more explanation see the Eclipse CLA FAQ ) regardless of how their contribution patch is provided.

Signing an Eclipse CLA

Log into the Eclipse projects forge (you will need to create an account with the Eclipse Foundation if you have not already done so); click on "Contributor License Agreement"; and Complete the form. Be sure to use the same email address when you create any Git commit records.

Use Bugzilla

Once a CLA has been signed, then patches should always be contributed with an associated project bugzilla. The CLA symbol next to the contributors name in the bugzilla should be green to indicate the CLA is on record. This will allow the authors contribution to both be tracked and acknowledged.

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. We don't really like this approach, but it is difficult to ignore how easy it is for the contributer. Just remember, you still need to create a CLA as mentioned above.

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 must come in through bugzilla for IP tracking purposes, even if they are coming in as commits through gerrit. 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 Internet Relay Chat - 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 frustrates a developer quite like a patch that doesn't apply.

RECOMMENDED - 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 must accept these sorts of patches only via bugzilla. Make sure your commit is using the email that you registered in your CLA or no amount of pushing the in world from us will get past the eclipse git commit hooks. When you do your commit to your local repo it is also vital that you "sign-off" on the commit using "git commit -s". Without the sign-off, your patch cannot be applied to the jetty repo because it will be rejected by the eclipse git commit hooks.

From the top level of the cloned project:

Make your changes and commit them locally using git commit -s:

      
$ git commit -s
 

Then use git log to identify the commit(s) you want to include in your patch:

      
commit 70e29326fe904675f772b88a67128c0b3529565e
Author: John Doe <john.doe@who.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 -M -B 70e29326fe904675f772b88a67128c0b3529565e
 

This will create a single patch file for each commit since the specified commit. The names will start with 0001-[commitmessage].patch. 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. It is critically important that developers applying these sorts of patches are fully aware of what is being committed and what they are accepting.

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

    
$ git am 0001-353563-HttpDestinationQueueTest-too-slow.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.

Note

It is intended that developers are also able to counter-sign the patch by using the '-s' option with the 'git am' command. However as the git hook that processes the commit currently has a bug it is recommended that developers do NOT use the -s option. See https://bugs.eclipse.org/bugs/show_bug.cgi?id=415307

Git Amend

If a committer is having trouble applying the patch cleanly with git am, they can use git commit --amend to modify the author and signoff the commit. For example:

      
$ git checkout -b patch
$ git apply john-doe.patch
$ git commit -a -m "<Original commit message from John Doe>"
    

At this point the patch is committed with the committer's name on a local branch

      
$ git commit --amend --author "John Doe <john.doe@who.com>" --signoff
    

Now the patch has the right author and it has been signed off

      
$ git checkout master
$ git merge patch
 

Now the local branch has been merged into master with the right author

      
$ git branch -d patch
$ git push
 

Contributing with Gerrit

Gerrit is a web based code review system, facilitating online code reviews for projects using the Git version control system.

Gerrit for Contributors

Prepare yourself for using gerrit by following the steps described here: https://git.eclipse.org/r/Documentation/user-upload.html

Then clone the jetty-project:

    
$ git clone ssh://git.eclipse.org:29418/jetty/org.eclipse.jetty.project
     

Stop. Make sure you have a bugzilla issue open for the change that you want to commit into gerrit for review. Also when you are ready to commit your change make sure that your commit starts with the bugzilla id. For example your commit should look like this:

     
$ git commit -m "[Bug 343532] fixed issue" <files>

Make sure to properly set the changeIds as described here: https://git.eclipse.org/r/Documentation/user-changeid.html

Make your changes, commit them as usual with git. Once done do:

    
$ git push ssh://git.eclipse.org:29418/jetty/org.eclipse.jetty.project HEAD:refs/for/master

Note the magic: HEAD:refs/for/master. Without gerrit will not permit you to push.

Review your changes on your gerrit dashboard: https://git.eclipse.org/r/#/

Finally get some coffee and relax. You've contributed something to jetty, woohooo. :)

Gerrit for Committers

Using gerrit is pretty simple. Once you have logged in you should first register your interest in the project repositories you want to be notified of patches on. This option is located under your user Settings near your name in the upper right hand corner. Click on 'Watched Projects' and then start typing 'jetty' into the project name box and it will offer completions for the jetty projects.

Now that you are watching the appropriate projects you should get email notifications of commits into gerrit. It is critical that you follow strict committer IP process when reviewing commits. Egregious violations of this process can result into committer status issues.

On the top of the screen click My -> Watched Changes for a list of the commits available for review. These represent people waiting to have their work reviewed. Once you select an issue to review you will see a list of changes at the bottom, click on these and look over the changes. You can have a dialog back and forth with the user through the comments on the patch. Providing they used the ChangeId setup correctly they will be able to issue updates to their patch for further review. Once you are happy with a review change set click on the Review button. This brings up a screen with three important questions.

Verified

Have you verified if this patch is acceptable.

Code Review

How acceptable is this review change set? Are you willing to testitfy that it is good enough or does it bear further review.

IP Clean

Does this commit follow acceptable IP guidelines? If anything looks suspicious then follow up with comments to clarify any potential issues. Commits with minor changes to existing classes and projects are fine and should reference a corresponding bugzilla id in their commit message.

Completely new features and large contributions require a corresponding CQ reference.

Assuming sufficient approval through the review process there will be an option to Review and Submit and the commit will pass through into jetty proper. You may also review and comment without submitting so the Review button is useful for clearly stating the reviewers comments and concerns regarding the three items mentioned above. Multiple reviewers are able to collaborate on a given patch as well.

Contributing via GitHub PullRequests

The jetty eclipse git repository is mirrored to github at http://github.com/eclipse/jetty.project. Github has a suite of collaboration tools for submitting and reviewing contributions, but unfortunately the Eclipse Foundations IP policy prevents direct merging of github pull requests. However, if a contributor makes a pull request and references that in a bugzilla with a signed CLA, then a Jetty committer should be able to fetch, merge and commit the pull requests without the need to create a separate patch.

Github pull requests for Committers

A committer can prepare their repository for accepting Github pull requests as follows:

$ git remote add github https://github.com/eclipse/jetty.project.git
$ git config --add remote.github.fetch "+refs/pull/*/head:refs/remotes/origin/pr/*"

A committer can then fetch the latest pull request and check them out as follows (for pull request #123):

$ git fetch github
$ git checkout pr/123

The committer can then use normal git commands to merge the contribution back to the master branch. The commits may need to be signed off so they can be pushed using the git amend technique above.

See an error or something missing? Contribute to this documentation at Github!(Generated: 2014-11-21T01:00:38-08:00)