The Tcpdump Group git mirrors - tcpdump/blob - CONTRIBUTING

   1 Some informations for Contributors
   2 ----------------------------------
   3 Your want to contribute to Tcpdump, Thanks!
   4 Please, read these lines.
   5
   6 1) Fork the Tcpdump repository on GitHub from
   7    https://github.com/the-tcpdump-group/tcpdump
   8    (See https://help.github.com/articles/fork-a-repo/)
   9
  10 2) Setup an optionnal Travis-CI build
  11    You can setup a travis build for your fork. So, your can test your changes
  12    on Linux and OSX before sending pull requests.
  13    (See http://docs.travis-ci.com/user/getting-started/)
  14
  15 3) Clone your repository
  16    git clone https://github.com/<username>/tcpdump.git
  17
  18 4) Do a 'touch .devel' in your working directory.
  19    Currently, the effect is
  20    a) add (via configure, in Makefile) some warnings options ( -Wall
  21    -Wmissing-prototypes -Wstrict-prototypes, ...) to the compiler if it
  22    supports these options,
  23    b) have the Makefile support "make depend" and the configure script run it.
  24
  25 5) Configure and build
  26    ./configure && make -s && make check
  27
  28 6) Add/update sample.pcap files
  29    We use tests directory to do regression tests on the dissection of captured
  30    packets, by running tcpdump against a savefile sample.pcap, created with -w
  31    option and comparing the results with a text file sample.out giving the
  32    expected results.
  33
  34    Any new/updated fields in a dissector must be present in a sample.pcap file
  35    and the corresponding output file.
  36
  37    Configuration is set in tests/TESTLIST.
  38    Each line in this file has the following format:
  39    test-name   sample.pcap   sample.out   tcpdump-options
  40
  41    the sample.out file can be build by:
  42    (cd tests && ../tcpdump -n -r sample.pcap tcpdump-options > sample.out)
  43
  44    It is often useful to have test outputs with different verbosity levels
  45    (none, -v, -vv, -vvv, etc.) depending on the code.
  46
  47 7) Test with 'make check'
  48    Don't send a pull request if 'make check' gives failed tests.
  49
  50 8) Rebase your commits against upstream/master
  51    (To keep linearity)
  52
  53 9) Initiate and send a pull request
  54    (See https://help.github.com/articles/using-pull-requests/)
  55
  56 Some remarks
  57 ------------
  58 a) A thorough reading of some other printers code is usefull.
  59
  60 b) Put the the normative reference if any as comments (RFC, etc.).
  61
  62 c) Put the the format of packets/headers/options as comments.
  63
  64 d) The printer may receive incomplete packet in the buffer, truncated at any
  65    random position, for example by capturing with '-s size' option.
  66    Thus use ND_TTEST, ND_TTEST2, ND_TCHECK or ND_TCHECK2 for bound checking.
  67    For ND_TCHECK2:
  68      Define : static const char tstr[] = " [|protocol]";
  69      Define a label: trunc
  70      Print with: ND_PRINT((ndo, "%s", tstr));
  71    You can test the code via:
  72      sudo ./tcpdump -s snaplen [-v][v][...] -i lo # in a terminal
  73      sudo tcpreplay -i lo sample.pcap             # in another terminal
  74    You should try several values for snaplen to do various truncation.
  75
  76 e) Do invalid packet checks in code: Think that your code can receive in input
  77    not only a valid packet but any arbitrary random sequence of octets (packet
  78    corrupted in transit or built by a fuzz tester).
  79
  80 f) Use 'struct tok' for indexed strings and print them with
  81    tok2str() or bittok2str() (for flags).
  82
  83 g) Avoid empty lines in output of printers.
  84
  85 h) A commit message must have:
  86    First line: Capitalized short summary in the imperative (70 chars or less)
  87
  88    Body: Detailed explanatory text, if necessary.  Fold up it to approximately
  89    72 characters. There must be an empty line separating the summary from
  90    the body.
  91
  92 i) Avoid non-ASCII characters in code and commit messages.
  93
  94 j) Use the style of the modified sources.
  95
  96 k) Don't mix declarations and code
  97
  98 l) Don't use // for comments
  99    Not all C compilers accept C++/C99 comments by default.
 100
 101 m) Avoid trailing tabs/spaces