The Tcpdump Group git mirrors - tcpdump/blob - CONTRIBUTING

   1 Some Information for Contributors
   2 ---------------------------------
   3 You want to contribute to Tcpdump, Thanks!
   4 Please, read these lines.
   5
   6
   7 How to report bugs and other problems
   8 -------------------------------------
   9 To report a security issue (segfault, buffer overflow, infinite loop, arbitrary
  10 code execution etc) please send an e-mail to security@tcpdump.org, do not use
  11 the bug tracker!
  12
  13 To report a non-security problem (failure to compile, incorrect output in the
  14 protocol printout, missing support for a particular protocol etc) please check
  15 first that it reproduces with the latest stable release of tcpdump and the latest
  16 stable release of libpcap. If it does, please check that the problem reproduces
  17 with the current git master branch of tcpdump and the current git master branch of
  18 libpcap. If it does (and it is not a security-related problem, otherwise see
  19 above), please navigate to https://github.com/the-tcpdump-group/tcpdump/issues
  20 and check if the problem has already been reported. If it has not, please open
  21 a new issue and provide the following details:
  22
  23 * tcpdump and libpcap version (tcpdump --version)
  24 * operating system name and version and any other details that may be relevant
  25   (uname -a, compiler name and version, CPU type etc.)
  26 * configure flags if any were used
  27 * statement of the problem
  28 * steps to reproduce
  29
  30 Please note that if you know exactly how to solve the problem and the solution
  31 would not be too intrusive, it would be best to contribute some development time
  32 and open a pull request instead as discussed below.
  33
  34 Still not sure how to do? Feel free to [subscribe](http://www.tcpdump.org/#mailing-lists)
  35 to the mailing list tcpdump-workers@lists.tcpdump.org and ask!
  36
  37
  38 How to add new code and to update existing code
  39 -----------------------------------------------
  40
  41 0) Check that there isn't a pull request already opened for the changes you
  42    intend to make.
  43
  44 1) Fork the Tcpdump repository on GitHub from
  45    https://github.com/the-tcpdump-group/tcpdump
  46    (See https://help.github.com/articles/fork-a-repo/)
  47
  48 2) Setup an optional Travis-CI build
  49    You can setup a travis build for your fork. So, you can test your changes
  50    on Linux and OSX before sending pull requests.
  51    (See http://docs.travis-ci.com/user/getting-started/)
  52
  53 3) Setup your git working copy
  54    git clone https://github.com/<username>/tcpdump.git
  55    cd tcpdump
  56    git remote add upstream https://github.com/the-tcpdump-group/tcpdump
  57    git fetch upstream
  58
  59 4) Do a 'touch .devel' in your working directory.
  60    Currently, the effect is
  61    a) add (via configure, in Makefile) some warnings options ( -Wall
  62    -Wmissing-prototypes -Wstrict-prototypes, ...) to the compiler if it
  63    supports these options,
  64    b) have the Makefile support "make depend" and the configure script run it.
  65
  66 5) Configure and build
  67    ./configure && make -s && make check
  68
  69 6) Add/update sample.pcap files
  70    We use tests directory to do regression tests on the dissection of captured
  71    packets.  Those captured packets were saved running tcpdump with option "-w
  72    sample.pcap".  Additional options like "-n" and "-t" are used to create
  73    relevant and reproducible output.  The actual test compares the current text
  74    output with the expected result (sample.out) saved from a previous version.
  75
  76    Any new/updated fields in a dissector must be present in a sample.pcap file
  77    and the corresponding output file.
  78
  79    Configuration is set in tests/TESTLIST.
  80    Each line in this file has the following format:
  81    test-name   sample.pcap   sample.out   tcpdump-options
  82
  83    The sample.out file can be build by:
  84    (cd tests && ../tcpdump -n -t -r sample.pcap tcpdump-options > sample.out)
  85
  86    Or, for convenience, use "./update-test.sh test-name"
  87
  88    It is often useful to have test outputs with different verbosity levels
  89    (none, -v, -vv, -vvv, etc.) depending on the code.
  90
  91 7) Test with 'make check'
  92    Don't send a pull request if 'make check' gives failed tests.
  93
  94 8) Try to rebase your commits to keep the history simple.
  95    git rebase upstream/master
  96    (If the rebase fails and you cannot resolve, issue "git rebase --abort"
  97    and ask for help in the pull request comment.)
  98
  99 9) Once 100% happy, put your work into your forked repository.
 100    git push
 101
 102 10) Initiate and send a pull request
 103    (See https://help.github.com/articles/using-pull-requests/)
 104
 105
 106 Code style and generic remarks
 107 ------------------------------
 108 a) A thorough reading of some other printers code is useful.
 109
 110 b) Put the normative reference if any as comments (RFC, etc.).
 111
 112 c) Put the format of packets/headers/options as comments if there is no
 113    published normative reference.
 114
 115 d) The printer may receive incomplete packet in the buffer, truncated at any
 116    random position, for example by capturing with '-s size' option.
 117    Thus use ND_TTEST, ND_TTEST2, ND_TCHECK or ND_TCHECK2 for bound checking.
 118    For ND_TCHECK2:
 119      Define : static const char tstr[] = " [|protocol]";
 120      Define a label: trunc
 121      Print with: ND_PRINT((ndo, "%s", tstr));
 122    You can test the code via:
 123      sudo ./tcpdump -s snaplen [-v][v][...] -i lo # in a terminal
 124      sudo tcpreplay -i lo sample.pcap             # in another terminal
 125    You should try several values for snaplen to do various truncation.
 126
 127 e) Do invalid packet checks in code: Think that your code can receive in input
 128    not only a valid packet but any arbitrary random sequence of octets (packet
 129    - built malformed originally by the sender or by a fuzz tester,
 130    - became corrupted in transit).
 131    Print with: ND_PRINT((ndo, "%s", istr));     /* to print " (invalid)" */
 132
 133 f) Use 'struct tok' for indexed strings and print them with
 134    tok2str() or bittok2str() (for flags).
 135
 136 g) Avoid empty lines in output of printers.
 137
 138 h) A commit message must have:
 139    First line: Capitalized short summary in the imperative (70 chars or less)
 140
 141    Body: Detailed explanatory text, if necessary. Fold it to approximately
 142    72 characters. There must be an empty line separating the summary from
 143    the body.
 144
 145 i) Avoid non-ASCII characters in code and commit messages.
 146
 147 j) Use the style of the modified sources.
 148
 149 k) Don't mix declarations and code
 150
 151 l) Don't use // for comments
 152    Not all C compilers accept C++/C99 comments by default.
 153
 154 m) Avoid trailing tabs/spaces