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