Notice: This Wiki is now read only and edits are no longer possible. Please see: https://gitlab.eclipse.org/eclipsefdn/helpdesk/-/wikis/Wiki-shutdown-plan for the plan.
Difference between revisions of "Jetty/Contributor/Contributing Patches"
(5 intermediate revisions by the same user not shown) | |||
Line 1: | Line 1: | ||
{{Jetty}} | {{Jetty}} | ||
− | + | {{Jetty Redirect|http://www.eclipse.org/jetty/documentation/current/contributing-patches.html}} | |
+ | |||
+ | This section describes how to contribute a patch to Jetty @ Eclipse. | ||
== Git Diff == | == Git Diff == | ||
− | The simplest way to contribute a patch is to | + | The simplest way to contribute a patch is to modify a cloned copy of jetty and then generate a diff between the original and the version that contains your patch. |
From the top level of the cloned project: | From the top level of the cloned project: | ||
Line 11: | Line 13: | ||
<tt>git diff > ######.patch</tt> | <tt>git diff > ######.patch</tt> | ||
− | The hash marks | + | The hash marks must be the Bugzilla issue that you are addressing. All patches coming into jetty @ eclipse must come through Bugzilla for IP tracking purposes. Depending on the size of the patch, the patch itself might be flagged as +iplog, which means it is subject to legal review and inclusion with our iplog from here to eternity. We are sorry, but we are unable to apply patches that we receive via email. If you have the Bugzilla issue created already, just attach the patch to it, and feel free to bug us on IRC to take a look. If there is no Bugzilla issue, create one, make sure the patch is named appropriately, and attach it. |
− | When the developer reviews the patch and | + | When the developer reviews the patch and applies it, they do so as follows: |
<tt>git apply < ######.patch</tt> | <tt>git apply < ######.patch</tt> | ||
− | If you want to be a nice person, test your patch on a clean clone to ensure that it applies cleanly. Nothing | + | 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. |
== Git Format Patch == | == 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 | + | 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 '<tt>git format-patch</tt> 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 can accept these sorts of patches only via Bugzilla. |
From the top level of the cloned project: | 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: | + | Make your changes and commit them locally using <tt>git commit</tt>. Then use <tt>git log</tt> to identify the commit(s) you want to include in your patch: |
<tt><pre> | <tt><pre> | ||
Line 35: | Line 37: | ||
</pre></tt> | </pre></tt> | ||
− | Use git format-patch to create the patch: | + | Use <tt>git format-patch</tt> to create the patch: |
<tt>git format-patch -M -B 70e29326fe904675f772b88a67128c0b3529565e</tt> | <tt>git format-patch -M -B 70e29326fe904675f772b88a67128c0b3529565e</tt> | ||
− | This | + | This creates a single patch file for each commit since the specified commit. The names start with <tt>0001-[commitmessage].patch</tt>. See http://www.kernel.org/pub/software/scm/git/docs/git-format-patch.html for details. |
− | When a developer | + | When a developer applies this sort of patch, they must assume responsibility for applying it to our codebase from the IP perspective. So the developer must be comfortable with the providence of the patch, and make sure that it is clear of potential issues. This is not like a diff that you get to edit and clean up issues before it is applied. The commit is recorded locally, and the developer then has a chance to make ''additional'' commits to address any lingering issues. It is critically important that developers applying these sorts of patches be fully aware of what is being committed and what they are signing off on. |
− | To apply the patch the developer | + | To apply the patch the developer uses a command like: |
<tt>git am -s 0001-353563-HttpDestinationQueueTest-too-slow.patch</tt> | <tt>git am -s 0001-353563-HttpDestinationQueueTest-too-slow.patch</tt> | ||
− | Providing it applies cleanly there | + | Providing it applies cleanly, there is now a commit in their local copy and they can either make additional commits or push it. The '-s' option attaches a 'Signed By: ' line to the commit with the developer's commit information. This is required; without it the eclipse git server rejects the commit as invalid. 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. |
== Git Amend == | == Git Amend == | ||
− | Alternatively, for troublesome patches that do not | + | Alternatively, for troublesome patches that do not apply cleanly with <tt>git am</tt>, you can use <tt>git commit --amend</tt> to modify the author and sign off the commit. |
For example: | For example: | ||
− | <pre> | + | <tt><pre> |
$ git checkout -b patch | $ git checkout -b patch | ||
− | $ git apply . | + | $ git apply john-doe.patch |
− | $ git commit | + | $ git commit -a -m "<Original commit message from John Doe>" |
+ | </pre></tt> | ||
− | At this point the patch is committed with | + | 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>" - | + | <tt><pre> |
+ | $ git commit --amend --author "John Doe <john.doe@who.com>" --signoff | ||
+ | </pre></tt> | ||
− | Now the patch has the | + | Now the patch has the correct author and it has been signed off. |
+ | <tt><pre> | ||
$ git checkout master | $ git checkout master | ||
$ git merge patch | $ git merge patch | ||
+ | </pre></tt> | ||
− | Now the local branch has been merged into master with the | + | Now the local branch has been merged into master with the correct author. |
+ | <tt><pre> | ||
$ git branch -d patch | $ git branch -d patch | ||
$ git push | $ git push | ||
− | </pre> | + | </pre></tt> |
== Using Gerrit @ Eclipse == | == Using Gerrit @ Eclipse == | ||
− | + | 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: | ||
+ | <tt><pre> | ||
+ | git clone ssh://git.eclipse.org:29418/jetty/org.eclipse.jetty.project | ||
+ | </pre></tt> | ||
+ | |||
+ | 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: | ||
+ | <tt><pre> | ||
+ | git push ssh://git.eclipse.org:29418/jetty/org.eclipse.jetty.project HEAD:refs/for/master | ||
+ | </pre></tt> | ||
+ | |||
+ | 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. :) |
Latest revision as of 15:55, 23 April 2013
This section describes how to contribute a patch to Jetty @ Eclipse.
Git Diff
The simplest way to contribute a patch is to modify a cloned copy of jetty and then generate a diff between the original and the version that contains your patch.
From the top level of the cloned project:
git diff > ######.patch
The hash marks must be the Bugzilla issue that you are addressing. All patches coming into jetty @ eclipse must come through Bugzilla for IP tracking purposes. Depending on the size of the patch, the patch itself might be flagged as +iplog, which means it is subject to legal review and inclusion with our iplog from here to eternity. We are sorry, but we are unable to apply patches that we receive via email. If you have the Bugzilla issue created already, just attach the patch to it, and feel free to bug us on IRC to take a look. If there is no Bugzilla issue, create one, make sure the patch is named appropriately, and attach it.
When the developer reviews the patch and applies it, they do so as follows:
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.
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 can accept these sorts of patches 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 -M -B 70e29326fe904675f772b88a67128c0b3529565e
This creates a single patch file for each commit since the specified commit. The names start with 0001-[commitmessage].patch. See http://www.kernel.org/pub/software/scm/git/docs/git-format-patch.html for details.
When a developer applies this sort of patch, they must assume responsibility for applying it to our codebase from the IP perspective. So the developer must be comfortable with the providence of the patch, and make sure that it is clear of potential issues. This is not like a diff that you get to edit and clean up issues before it is applied. The commit is recorded locally, and the developer then has a chance to make additional commits to address any lingering issues. It is critically important that developers applying these sorts of patches be fully aware of what is being committed and what they are signing off on.
To apply the patch the developer uses a command like:
git am -s 0001-353563-HttpDestinationQueueTest-too-slow.patch
Providing it applies cleanly, there is now a commit in their local copy and they can either make additional commits or push it. The '-s' option attaches a 'Signed By: ' line to the commit with the developer's commit information. This is required; without it the eclipse git server rejects the commit as invalid. 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.
Git Amend
Alternatively, for troublesome patches that do not apply cleanly with git am, you can use git commit --amend to modify the author and sign off 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 correct author and it has been signed off.
$ git checkout master $ git merge patch
Now the local branch has been merged into master with the correct author.
$ git branch -d patch $ git push
Using Gerrit @ Eclipse
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
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. :)