winery/CONTRIBUTING.md

   1 (This is based on the [Jetty Contributing Patches] documentation)
   2
   3 # Contributing Patches
   4 This file describes how to contribute a patch to the Winery project.
   5 You should first familiarize yourself with the Eclipse wiki page on [contributing via Git].
   6
   7 ## Sign a CLA
   8 The Eclipse Foundation has a strong Intellectual Property policy which tracks contributions in detail to ensure that:
   9
  10 * Did the contributor author 100% of the content?
  11 * Does the contributor have the rights to contribute this content to Eclipse?
  12 * Is the contribution under the project's license(s) (e.g. [EPL])
  13
  14 Thus a contributor needs to e-sign a [Contributor License Agreement] (for more explanation see the Eclipse [CLA FAQ]) regardless of how their contribution patch is provided.
  15
  16 ### Signing an Eclipse CLA
  17 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.
  18
  19 ## Use Bugzilla
  20 Once a CLA has been signed, then patches should always be contributed with an associated [project bugzilla].
  21 The CLA symbol next to the contributors name in the bugzilla should be green to indicate the CLA is on record.
  22 This will allow the authors contribution to both be tracked and acknowledged.
  23
  24 ## Git Diff
  25 The simplest way to contribute a patch is to make a modification to a cloned copy of Winery and then generate a diff between the two versions.
  26 We don't really like this approach, but it is difficult to ignore how easy it is for the contributer.
  27 Just remember, you still need to create a CLA as mentioned above.
  28
  29 From the top level of the cloned project:
  30
  31     $ git diff > ######.patch
  32
  33 The hash marks should be the bugzilla issue that you will be attaching the issue to.
  34 All patches coming into Winery must come in through bugzilla for IP tracking purposes.
  35 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.
  36 We are sorry we are unable to apply patches that we receive via email.
  37 So if you have the bugzilla issue created already just attach the issue.
  38 If there is no bugzilla issue yet, create one, make sure the patch is named appropriately and attach it.
  39
  40 When the developer reviews the patch and goes to apply it they will use:
  41
  42     $ git apply < ######.patch
  43
  44 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.
  45
  46 ## RECOMMENDED - Git Format Patch
  47 Another approach if you want your name in shiny lights in our commit logs is to use the format patch option.
  48 With this approach you commit into your cloned copy of Winery and use the git format patch option to generate what looks like an email message containing all of the commit information.
  49 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.
  50 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.
  51 When you do your commit to your local repo it is also vital that you "sign-off" on the commit using `git commit -s`.
  52 Without the sign-off, your patch cannot be applied to the jetty repo because it will be rejected by the eclipse git commit hooks.
  53
  54 From the top level of the cloned project:
  55
  56 Make your changes and commit them locally using `git commit -s`:
  57
  58     $ git commit -s
  59
  60 Then use `git log` to identify the commit(s) you want to include in your patch:
  61
  62     commit 70e29326fe904675f772b88a67128c0b3529565e
  63     Author: John Doe <john.doe@who.com>
  64     Date: Tue Aug 2 14:36:50 2011 +0200 353563:
  65     HttpDestinationQueueTest too slow
  66
  67 Use `git format-patch` to create the patch:
  68
  69     $ git format-patch -M -B 70e29326fe904675f772b88a67128c0b3529565e
  70
  71 This will create a single patch file for each commit since the specified commit.
  72 The names will start with `0001-[commitmessage].patch`.
  73 See http://www.kernel.org/pub/software/scm/git/docs/git-format-patch.html for details.
  74
  75 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.
  76 So we must be comfortable with the providence of the patch and that it is clear of potential issues.
  77 This is not like a diff where you get to edit it and clean up issues before it gets applied.
  78 The commit is recorded locally and the developer will then have a chance to make additional commits to address any lingering issues.
  79 It is critically important that developers applying these sorts of patches are fully aware of what is being committed and what they are accepting.
  80
  81 To apply the patch the developer will use a command like:
  82
  83     $ git am 0001-353563-HttpDestinationQueueTest-too-slow.patch
  84
  85 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.
  86
  87 ### Note
  88 It is intended that developers are also able to counter-sign the patch by using the `-s` option with the `git am` command.
  89 However as the git hook that processes the commit currently has a bug it is recommended that developers do NOT use the `-s` option.
  90 See https://bugs.eclipse.org/bugs/show_bug.cgi?id=415307
  91
  92 ## Git Amend
  93 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:
  94
  95     $ git checkout -b patch
  96     $ git apply john-doe.patch
  97     $ git commit -a -m "<Original commit message from John Doe>"
  98
  99 At this point the patch is committed with the committer's name on a local branch
 100
 101     $ git commit --amend --author "John Doe <john.doe@who.com>" --signoff
 102
 103 Now the patch has the right author and it has been signed off
 104
 105     $ git checkout master
 106     $ git merge patch
 107
 108 Now the local branch has been merged into master with the right author
 109
 110     $ git branch -d patch
 111     $ git push
 112
 113 ## Contributing via Gerrit
 114 Winery currently has no Gerrit infrastructure in place.
 115 In case, we will receive a lot of patches, we will enable [the Eclipse Gerrit workflow](https://wiki.eclipse.org/Gerrit).
 116
 117 ## Contributing via Github PullRequests
 118 The Winery eclipse git repository is mirrored to github at http://github.com/winery/winery.
 119 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.
 120 However, if a contributor makes a pull request and references that in a bugzilla with a signed CLA, then a Winery committer should be able to fetch, merge and commit the pull requests without the need to create a separate patch.
 121
 122 ## Github pull requests for Committers
 123 A committer can prepare their repository for accepting Github pull requests as follows:
 124
 125     $ git remote add github https://github.com/winery/winery.git
 126     $ git config --add remote.github.fetch "+refs/pull/*/head:refs/remotes/origin/pr/*"
 127
 128 A committer can then fetch the latest pull request and check them out as follows (for pull request #123):
 129
 130     $ git fetch github
 131     $ git checkout pr/123
 132
 133 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.
 134
 135  [CLA FAQ]: https://www.eclipse.org/legal/clafaq.php
 136  [Contributor License Agreement]: https://www.eclipse.org/legal/CLA.php
 137  [contributing via Git]: http://wiki.eclipse.org/Development_Resources/Contributing_via_Git
 138  [Eclipse projects forge]: https://projects.eclipse.org/user/login/sso
 139  [EPL]: https://www.eclipse.org/legal/epl-v10.html
 140  [Jetty Contributing Patches]: https://www.eclipse.org/jetty/documentation/current/contributing-patches.html
 141  [project bugzilla]: https://bugs.eclipse.org/bugs/describecomponents.cgi?product=Winery