| 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 <[email protected]>. 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 <[email protected]>" 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 ([email protected]) 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 |
([email protected]) 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 <[email protected]> |
| 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 <[email protected]> |
| 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. |