1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
|
<html><head>
<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
<title>Contributing Patches</title><link rel="stylesheet" type="text/css" href="css/docbook.css"><meta name="generator" content="DocBook XSL-NS Stylesheets V1.76.1"><meta name="keywords" content="jetty, servlet, servlet-api, cometd, http, spdy, websocket, eclipse, maven, java, server, software"><link rel="home" href="index.html" title="Jetty : The Definitive Reference"><link rel="up" href="advanced-contributing.html" title="Chapter 34. Contributing to Jetty"><link rel="prev" href="bugs.html" title="Issues, Features, and Bugs"><link rel="next" href="releasing-jetty.html" title="Releasing Jetty"><link xmlns:jfetch="java:org.eclipse.jetty.xslt.tools.JavaSourceFetchExtension" xmlns:fetch="java:org.eclipse.jetty.xslt.tools.SourceFetchExtension" xmlns:d="http://docbook.org/ns/docbook" xmlns:l="http://docbook.sourceforge.net/xmlns/l10n/1.0" xmlns:xslthl="http://xslthl.sf.net" xmlns:gcse="http://www.google.com" xmlns:date="http://exslt.org/dates-and-times" rel="shortcut icon" href="images/favicon.ico"><script type="text/javascript" src="js/shCore.js"></script><script type="text/javascript" src="js/shBrushJava.js"></script><script type="text/javascript" src="js/shBrushXml.js"></script><script type="text/javascript" src="js/shBrushBash.js"></script><script type="text/javascript" src="js/shBrushJScript.js"></script><script type="text/javascript" src="js/shBrushSql.js"></script><script type="text/javascript" src="js/shBrushProperties.js"></script><script type="text/javascript" src="js/shBrushPlain.js"></script><link type="text/css" rel="stylesheet" href="css/shCore.css"><link type="text/css" rel="stylesheet" href="css/shThemeEclipse.css"><link type="text/css" rel="stylesheet" href="css/font-awesome.min.css"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><table xmlns:jfetch="java:org.eclipse.jetty.xslt.tools.JavaSourceFetchExtension" xmlns:fetch="java:org.eclipse.jetty.xslt.tools.SourceFetchExtension" xmlns:d="http://docbook.org/ns/docbook" xmlns:l="http://docbook.sourceforge.net/xmlns/l10n/1.0" xmlns:xslthl="http://xslthl.sf.net" xmlns:gcse="http://www.google.com" xmlns:date="http://exslt.org/dates-and-times"><tr><td style="width: 25%"><a href="http://www.eclipse.org/jetty"><img src="images/jetty-header-logo.png" alt="Jetty Logo"></a><br><span style="font-size: small">
Version: 9.2.3.v20140905</span></td><td style="width: 50%"><script type="text/javascript"> (function() {
var cx = '016459005284625897022:obd4lsai2ds';
var gcse = document.createElement('script');
gcse.type = 'text/javascript';
gcse.async = true;
gcse.src = (document.location.protocol == 'https:' ? 'https:' : 'http:') +
'//www.google.com/cse/cse.js?cx=' + cx;
var s = document.getElementsByTagName('script')[0];
s.parentNode.insertBefore(gcse, s);
})();
</script><gcse:search></gcse:search></td></tr></table><div xmlns:jfetch="java:org.eclipse.jetty.xslt.tools.JavaSourceFetchExtension" xmlns:fetch="java:org.eclipse.jetty.xslt.tools.SourceFetchExtension" xmlns:d="http://docbook.org/ns/docbook" xmlns:l="http://docbook.sourceforge.net/xmlns/l10n/1.0" xmlns:xslthl="http://xslthl.sf.net" xmlns:gcse="http://www.google.com" xmlns:date="http://exslt.org/dates-and-times" class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Contributing Patches</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="bugs.html"><i class="icon-chevron-left"></i> Previous</a> </td><th width="60%" align="center">Chapter 34. Contributing to Jetty<br><a accesskey="p" href="index.html"><i class="icon-home"></i> Home</a></th><td width="20%" align="right"> <a accesskey="n" href="releasing-jetty.html">Next <i class="icon-chevron-right"></i></a></td></tr></table><hr></div><div xmlns:jfetch="java:org.eclipse.jetty.xslt.tools.JavaSourceFetchExtension" xmlns:fetch="java:org.eclipse.jetty.xslt.tools.SourceFetchExtension" xmlns:d="http://docbook.org/ns/docbook" xmlns:l="http://docbook.sourceforge.net/xmlns/l10n/1.0" xmlns:xslthl="http://xslthl.sf.net" xmlns:gcse="http://www.google.com" xmlns:date="http://exslt.org/dates-and-times" class="jetty-callout"><h5 class="callout"><a href="http://www.webtide.com/">Contact the core Jetty developers at
<span class="website">www.webtide.com</span></a></h5><p>
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
</p></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="contributing-patches"></a>Contributing Patches</h2></div></div></div><div class="toc"><dl><dt><span class="section"><a href="contributing-patches.html#contributing-cla">Sign a CLA</a></span></dt><dt><span class="section"><a href="contributing-patches.html#d0e23701">Use Bugzilla</a></span></dt><dt><span class="section"><a href="contributing-patches.html#git-diff">Git Diff</a></span></dt><dt><span class="section"><a href="contributing-patches.html#d0e23729">RECOMMENDED - Git Format Patch</a></span></dt><dt><span class="section"><a href="contributing-patches.html#d0e23789">Contributing with Gerrit</a></span></dt><dt><span class="section"><a href="contributing-patches.html#d0e23864">Contributing via GitHub PullRequests</a></span></dt></dl></div><p>How to contribute a patch to the jetty project. You should first
familiarize yourself with the Eclipse wiki page on <a class="link" href="http://wiki.eclipse.org/Development_Resources/Contributing_via_Git" target="_top">contributing
via Git</a>.</p><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="contributing-cla"></a>Sign a CLA</h3></div></div></div><p>The Eclipse Foundation has a strong Intelectual Property policy
which tracks contributions in detail to ensure that:</p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"><p>Did the contributor author 100% of the content?</p></li><li class="listitem"><p>Does the contributor have the rights to contribute this content
to Eclipse?</p></li><li class="listitem"><p>Is the contribution under the project’s license(s) (e.g.
EPL)</p></li></ol></div><p>Thus a contributor needs to e-sign a <a class="link" href="???" target="_top">Contributor
Licence Agreement</a> (for more explanation see the <a class="link" href="http://www.eclipse.org/legal/clafaq.php" target="_top">Eclipse CLA FAQ</a> )
regardless of how their contribution patch is provided.</p><div xmlns:jfetch="java:org.eclipse.jetty.xslt.tools.JavaSourceFetchExtension" xmlns:fetch="java:org.eclipse.jetty.xslt.tools.SourceFetchExtension" xmlns:d="http://docbook.org/ns/docbook" xmlns:l="http://docbook.sourceforge.net/xmlns/l10n/1.0" xmlns:xslthl="http://xslthl.sf.net" xmlns:gcse="http://www.google.com" xmlns:date="http://exslt.org/dates-and-times" class="tip" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title"><i class="icon-lightbulb"></i> Signing an Eclipse CLA</h3><p>Log into the <a class="link" href="https://projects.eclipse.org/user/login/sso" target="_top">Eclipse projects
forge</a> (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.</p></div></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="d0e23701"></a>Use Bugzilla</h3></div></div></div><p>Once a CLA has been signed, then patches should always be
contributed with an associated <a class="link" href="???" target="_top">project
bugzilla</a>. 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.</p></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="git-diff"></a>Git Diff</h3></div></div></div><p>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.</p><p>From the top level of the cloned project:</p><div class="screenexample"><pre class="screen">
$ git diff > ######.patch
</pre></div><p>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 <a class="xref" href="advanced-contributing.html#community-irc" title="Internet Relay Chat - IRC">Internet Relay Chat - IRC</a> to take a look. If there is no bugzilla issue yet, create one,
make sure the patch is named appropriately and attach it.</p><p>When the developer reviews the patch and goes to apply it they will
use:</p><div class="screenexample"><pre class="screen">
$ git apply < ######.patch
</pre></div><p>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.</p></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="d0e23729"></a>RECOMMENDED - Git Format Patch</h3></div></div></div><p>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 <span class="emphasis"><em>vital</em></span> 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.</p><p>From the top level of the cloned project:</p><p>Make your changes and commit them locally using <code class="code">git commit
-s</code>:</p><div class="screenexample"><pre class="screen">
$ git commit -s
</pre></div><p>Then use git log to identify the commit(s) you want to include in
your patch:</p><div class="screenexample"><pre class="screen">
commit 70e29326fe904675f772b88a67128c0b3529565e
Author: John Doe <john.doe@who.com>
Date: Tue Aug 2 14:36:50 2011 +0200 353563:
HttpDestinationQueueTest too slow
</pre></div><p>Use git format-patch to create the patch:</p><div class="screenexample"><pre class="screen">
$ git format-patch -M -B 70e29326fe904675f772b88a67128c0b3529565e
</pre></div><p>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.</p><p>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.</p><p>To apply the patch the developer will use a command like:</p><div class="screenexample"><pre class="screen">
$ git am 0001-353563-HttpDestinationQueueTest-too-slow.patch
</pre></div><p>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.</p><div xmlns:jfetch="java:org.eclipse.jetty.xslt.tools.JavaSourceFetchExtension" xmlns:fetch="java:org.eclipse.jetty.xslt.tools.SourceFetchExtension" xmlns:d="http://docbook.org/ns/docbook" xmlns:l="http://docbook.sourceforge.net/xmlns/l10n/1.0" xmlns:xslthl="http://xslthl.sf.net" xmlns:gcse="http://www.google.com" xmlns:date="http://exslt.org/dates-and-times" class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title"><i class="icon-asterisk"></i> Note</h3><p>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 <a class="link" href="https://bugs.eclipse.org/bugs/show_bug.cgi?id=415307" target="_top">https://bugs.eclipse.org/bugs/show_bug.cgi?id=415307</a></p></div><div class="section"><div class="titlepage"><div><div><h4 class="title"><a name="git-amend"></a>Git Amend</h4></div></div></div><p>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:</p><div class="screenexample"><pre class="screen">
$ git checkout -b patch
$ git apply john-doe.patch
$ git commit -a -m "<Original commit message from John Doe>"
</pre></div><p>At this point the patch is committed with the committer's name on
a local branch</p><div class="screenexample"><pre class="screen">
$ git commit --amend --author "John Doe <john.doe@who.com>" --signoff
</pre></div><p>Now the patch has the right author and it has been signed
off</p><div class="screenexample"><pre class="screen">
$ git checkout master
$ git merge patch
</pre></div><p>Now the local branch has been merged into master with the right
author</p><div class="screenexample"><pre class="screen">
$ git branch -d patch
$ git push
</pre></div></div></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="d0e23789"></a>Contributing with Gerrit</h3></div></div></div><p><a class="link" href="https://wiki.eclipse.org/Gerrit" target="_top">Gerrit</a> is a
web based code review system, facilitating online code reviews for
projects using the Git version control system.</p><div class="section"><div class="titlepage"><div><div><h4 class="title"><a name="gerrit-for-contributors"></a>Gerrit for Contributors</h4></div></div></div><p>Prepare yourself for using gerrit by following the steps described
here: <a class="link" href="https://git.eclipse.org/r/Documentation/user-upload.html" target="_top">https://git.eclipse.org/r/Documentation/user-upload.html</a></p><p>Then clone the jetty-project:</p><div class="screenexample"><pre class="screen">
$ git clone ssh://git.eclipse.org:29418/jetty/org.eclipse.jetty.project
</pre></div><p><span class="emphasis"><em>Stop.</em></span> 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:</p><div class="screenexample"><pre class="screen">
$ git commit -m "[Bug 343532] fixed issue" <files>
</pre></div><p>Make sure to properly set the changeIds as described here: <a class="link" href="https://git.eclipse.org/r/Documentation/user-changeid.html" target="_top">https://git.eclipse.org/r/Documentation/user-changeid.html</a></p><p>Make your changes, commit them as usual with git. Once done
do:</p><div class="screenexample"><pre class="screen">
$ git push ssh://git.eclipse.org:29418/jetty/org.eclipse.jetty.project HEAD:refs/for/master
</pre></div><p>Note the magic: <code class="code">HEAD:refs/for/master</code>. Without gerrit
will not permit you to push.</p><p>Review your changes on your gerrit dashboard: <a class="link" href="https://git.eclipse.org/r/#/" target="_top">https://git.eclipse.org/r/#/</a></p><p>Finally get some coffee and relax. You've contributed something to
jetty, woohooo. :)</p></div><div class="section"><div class="titlepage"><div><div><h4 class="title"><a name="gerrit-for-committers"></a>Gerrit for Committers</h4></div></div></div><p>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.</p><p>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.</p><p>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.</p><div class="variablelist"><dl><dt><span class="term">Verified</span></dt><dd><p>Have you verified if this patch is acceptable.</p></dd><dt><span class="term">Code Review</span></dt><dd><p>How acceptable is this review change set? Are you willing to
testitfy that it is good enough or does it bear further
review.</p></dd><dt><span class="term">IP Clean</span></dt><dd><p>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.</p><p>Completely new features and large contributions require a
corresponding CQ reference.</p></dd></dl></div><p>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.</p></div></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="d0e23864"></a>Contributing via GitHub PullRequests</h3></div></div></div><p>The jetty eclipse git repository is mirrored to github at <a class="link" href="https://github.com/eclipse/jetty.project" target="_top">http://github.com/eclipse/jetty.project</a>.
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.</p><div class="section"><div class="titlepage"><div><div><h4 class="title"><a name="d0e23872"></a>Github pull requests for Committers</h4></div></div></div><p>A committer can prepare their repository for accepting Github pull
requests as follows:</p><div class="screenexample"><pre class="screen">$ git remote add github https://github.com/eclipse/jetty.project.git
$ git config --add remote.github.fetch "+refs/pull/*/head:refs/remotes/origin/pr/*"</pre></div><p>A committer can then fetch the latest pull request and check them
out as follows (for pull request #123):</p><div class="screenexample"><pre class="screen">$ git fetch github
$ git checkout pr/123</pre></div><p>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.</p></div></div></div><script type="text/javascript">
SyntaxHighlighter.all()
</script><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="bugs.html"><i class="icon-chevron-left"></i> Previous</a> </td><td width="20%" align="center"><a accesskey="u" href="advanced-contributing.html"><i class="icon-chevron-up"></i> Top</a></td><td width="40%" align="right"> <a accesskey="n" href="releasing-jetty.html">Next <i class="icon-chevron-right"></i></a></td></tr><tr><td width="40%" align="left" valign="top">Issues, Features, and Bugs </td><td width="20%" align="center"><a accesskey="h" href="index.html"><i class="icon-home"></i> Home</a></td><td width="40%" align="right" valign="top"> Releasing Jetty</td></tr></table></div><p xmlns:jfetch="java:org.eclipse.jetty.xslt.tools.JavaSourceFetchExtension" xmlns:fetch="java:org.eclipse.jetty.xslt.tools.SourceFetchExtension" xmlns:d="http://docbook.org/ns/docbook" xmlns:l="http://docbook.sourceforge.net/xmlns/l10n/1.0" xmlns:xslthl="http://xslthl.sf.net" xmlns:gcse="http://www.google.com" xmlns:date="http://exslt.org/dates-and-times"><div class="jetty-callout">
See an error or something missing?
<span class="callout"><a href="http://github.com/jetty-project/jetty-documentation">Contribute to this documentation at
<span class="website"><i class="icon-github"></i> Github!</span></a></span><span style="float: right"><i>(Generated: 2014-11-13T01:00:39-08:00)</i></span></div></p><script xmlns:jfetch="java:org.eclipse.jetty.xslt.tools.JavaSourceFetchExtension" xmlns:fetch="java:org.eclipse.jetty.xslt.tools.SourceFetchExtension" xmlns:d="http://docbook.org/ns/docbook" xmlns:l="http://docbook.sourceforge.net/xmlns/l10n/1.0" xmlns:xslthl="http://xslthl.sf.net" xmlns:gcse="http://www.google.com" xmlns:date="http://exslt.org/dates-and-times" type="text/javascript">
var _gaq = _gaq || [];
_gaq.push(['_setAccount', 'UA-1149868-7']);
_gaq.push(['_trackPageview']);
(function() {
var ga = document.createElement('script'); ga.type = 'text/javascript'; ga.async = true;
ga.src = ('https:' == document.location.protocol ? 'https://ssl' : 'http://www') + '.google-analytics.com/ga.js';
var s = document.getElementsByTagName('script')[0]; s.parentNode.insertBefore(ga, s);
})();
</script></body></html>
|
