Documentation/SubmittingPatches

   1 Checklist for Patches:
   2 //////////////////////
   3
   4 Submitting patches should follow this guideline (derived from the Git project):
   5
   6 If you are familiar with upstream Linux kernel development, then you do not
   7 need to read this file, it's basically the same process.
   8
   9 * Commits:
  10
  11 - make sure to comply with the coding guidelines (see CodingStyle)
  12 - make commits of logical units
  13 - check for unnecessary whitespace with "git diff --check" before committing
  14 - do not check in commented out code or unneeded files
  15 - the first line of the commit message should be a short description (50
  16   characters is the soft limit, see DISCUSSION in git-commit(1)), and should
  17   skip the full stop
  18 - the body should provide a meaningful commit message, which:
  19   . explains the problem the change tries to solve, iow, what is wrong with
  20     the current code without the change.
  21   . justifies the way the change solves the problem, iow, why the result with
  22     the change is better.
  23   . alternate solutions considered but discarded, if any.
  24 - describe changes in imperative mood, e.g. "make xyzzy do frotz" instead of
  25   "[This patch] makes xyzzy do frotz" or "[I] changed xyzzy to do frotz", as
  26   if you are giving orders to the codebase to change its behaviour.
  27 - try to make sure your explanation can be understood without external
  28   resources. Instead of giving a URL to a mailing list archive, summarize the
  29   relevant points of the discussion.
  30 - add a "Signed-off-by: Your Name <you@example.com>" line to the commit message
  31   (or just use the option "-s" when committing) to confirm that you agree to
  32   the Developer's Certificate of Origin (see also
  33   http://linux.yyz.us/patch-format.html or below); this is mandatory
  34 - make sure syntax of man-pages is free of errors: podchecker <tool>.c
  35
  36 * For Patches via GitHub:
  37
  38 - fork the netsniff-ng project on GitHub to your local GitHub account
  39   (https://github.com/gnumaniacs/netsniff-ng)
  40 - make your changes to the latest master branch with respect to the commit
  41   section above
  42 - if you change, add, or remove a command line option or make some other user
  43   interface change, the associated documentation should be updated as well.
  44 - open a pull request on (https://github.com/gnumaniacs/netsniff-ng) and send
  45   a notification to the list (netsniff-ng@googlegroups.com) and CC one of the
  46   maintainers if (and only if) the patch is ready for inclusion.
  47 - if your name is not writable in ASCII, make sure that you send off a message
  48   in the correct encoding.
  49 - add a short description what the patch or patchset is about
  50
  51 * For Patches via Mail:
  52
  53 - use "git format-patch -M" to create the patch
  54 - do not PGP sign your patch
  55 - do not attach your patch, but read in the mail body, unless you cannot teach
  56   your mailer to leave the formatting of the patch alone.
  57 - be careful doing cut & paste into your mailer, not to corrupt whitespaces.
  58 - provide additional information (which is unsuitable for the commit message)
  59   between the "---" and the diffstat
  60 - if you change, add, or remove a command line option or make some other user
  61   interface change, the associated documentation should be updated as well.
  62 - if your name is not writable in ASCII, make sure that you send off a message
  63   in the correct encoding.
  64 - send the patch to the list (netsniff-ng@googlegroups.com) and CC one of the
  65   maintainers if (and only if) the patch is ready for inclusion. If you use
  66   git-send-email(1), please test it first by sending email to yourself.
  67
  68 * What does the 'Signed-off-by' mean?
  69
  70   It certifies the following (extract from the Linux kernel documentation):
  71
  72   Developer's Certificate of Origin 1.1
  73
  74   By making a contribution to this project, I certify that:
  75   (a) The contribution was created in whole or in part by me and I
  76       have the right to submit it under the open source license
  77       indicated in the file; or
  78   (b) The contribution is based upon previous work that, to the best
  79       of my knowledge, is covered under an appropriate open source
  80       license and I have the right under that license to submit that
  81       work with modifications, whether created in whole or in part
  82       by me, under the same open source license (unless I am
  83       permitted to submit under a different license), as indicated
  84       in the file; or
  85   (c) The contribution was provided directly to me by some other
  86       person who certified (a), (b) or (c) and I have not modified it.
  87   (d) I understand and agree that this project and the contribution
  88       are public and that a record of the contribution (including all
  89       personal information I submit with it, including my sign-off) is
  90       maintained indefinitely and may be redistributed consistent with
  91       this project or the open source license(s) involved.
  92
  93   then you just add a line saying
  94     Signed-off-by: Random J Developer <random@developer.example.org>
  95   using your real name (sorry, no pseudonyms or anonymous contributions).
  96
  97 * Example commit:
  98
  99   Please write good git commit messages. A good commit message looks like this:
 100
 101         Header line: explaining the commit in one line
 102
 103         Body of commit message is a few lines of text, explaining things
 104         in more detail, possibly giving some background about the issue
 105         being fixed, etc etc.
 106
 107         The body of the commit message can be several paragraphs, and
 108         please do proper word-wrap and keep columns shorter than about
 109         74 characters or so. That way "git log" will show things
 110         nicely even when it's indented.
 111
 112         Reported-by: whoever-reported-it
 113         Signed-off-by: Your Name <youremail@yourhost.com>
 114
 115   where that header line really should be meaningful, and really should be
 116   just one line.  That header line is what is shown by tools like gitk and
 117   shortlog, and should summarize the change in one readable line of text,
 118   independently of the longer explanation.
 119
 120 Note that future (0.5.7 onwards) changelogs will include a summary that is
 121 generated by 'git shortlog -n'. Hence, that's why we need you to stick to
 122 the convention.