SUBMITTING_PATCHES

   1 Short Version:
   2
   3  - Make small logical changes.
   4  - Provide a meaningful commit message.
   5
   6  - Review and follow the Eclipse Due Diligence Process
   7
   8      http://www.eclipse.org/projects/dev_process/ip-process-in-cartoons.php
   9      http://www.eclipse.org/legal/EclipseLegalProcessPoster.pdf
  10
  11  - Review and follow the current guidelines:
  12
  13      http://wiki.eclipse.org/EGit/Contributor_Guide
  14
  15
  16 Long Version:
  17
  18 I wanted a file describing how to submit patches for JGit,
  19 so I started with the one found in the core Git distribution
  20 (Documentation/SubmittingPatches), which itself was based on the
  21 patch submission guidelines for the Linux kernel.
  22
  23 However there are quite a few differences, so please review and
  24 familiarize yourself with the following relevant bits:
  25
  26
  27 (1) Make separate commits for logically separate changes.
  28
  29 Unless your patch is really trivial, you should not be sending
  30 out a patch that was generated between your working tree and your
  31 commit head.  Instead, always make a commit with complete commit
  32 message and generate a series of patches from your repository.
  33 It is a good discipline.
  34
  35 Describe the technical detail of the change(s).
  36
  37 If your description starts to get too long, that's a sign that you
  38 probably need to split up your commit to finer grained pieces.
  39
  40 I am very picky about formatting.  Make sure your final version
  41 of every file was formatted using the Eclipse code formatter
  42 using the project specific settings (Properties->Java Code
  43 Style->Formatter->"Java Conventions [built-in]").
  44
  45
  46 (2) Generate your patch using git tools out of your commits.
  47
  48 git based diff tools (git, and StGIT included) generate unidiff,
  49 which is the only acceptable format.
  50
  51 You do not have to be afraid to use -M option to "git diff" or "git
  52 format-patch", if your patch involves file renames.  The receiving
  53 end can handle them just fine.
  54
  55 Please make sure your patch does not include any extra files which
  56 do not belong in a patch submission.  Make sure to review your
  57 patch after generating it, to ensure accuracy.  Before sending out,
  58 please make sure it cleanly applies to the "master" branch head.
  59
  60
  61 (3) Check the license.
  62
  63 JGit is licensed under the Eclipse Distribution License (EDL,
  64 http://www.eclipse.org/org/documents/edl-v10.html), which is a
  65 renamed version of the new style/3-clause BSD license.
  66
  67 Under this licensing model *every* file within the project
  68 *must* list which license covers it in the header of the file.
  69 Any new contributions to an existing file *must* be submitted under
  70 the current license of that file.  Any new files *must* clearly
  71 indicate which license they are provided under in the file header.
  72
  73 Please verify that you are legally allowed and willing to submit your
  74 changes under the license covering each file *prior* to submitting
  75 your patch.  It is virtually impossible to remove a patch once it
  76 has been applied and pushed out.
  77
  78
  79 (4) Review the Eclipse Due Diligence Process.
  80
  81   http://www.eclipse.org/legal/EclipseLegalProcessPoster.pdf
  82
  83
  84 (5) Sending your patches.
  85
  86 "git format-patch" command follows the best current practice to
  87 format a commit as a reviewable text message.
  88
  89 At the beginning of the patch should come your commit message,
  90 a line that consists of three dashes, followed by the diffstat
  91 information and the patch itself.  If you are forwarding a patch
  92 from somebody else, optionally, at the beginning of the e-mail
  93 message just before the commit message starts, you can put a "From:
  94 " line to name that person.
  95
  96 You often want to add additional explanation about the patch,
  97 other than the commit message itself.  Place such "cover letter"
  98 material between the three dash lines and the diffstat, or please
  99 place it in the bug description itself.
 100
 101 Open a new bug on the Eclipse bug tracker on the EGit project:
 102
 103   https://bugs.eclipse.org/bugs/enter_bug.cgi?product=EGit
 104
 105 Attach the mailbox file(s) created by "git format-patch" to the bug.
 106