The Tcpdump Group git mirrors - tcpdump/blob - CONTRIBUTING

   1 Some Information for Contributors
   2 ---------------------------------
   3 Thank you for considering to make a contribution to tcpdump! Please use the
   4 guidelines below to achieve the best results and experience for everyone.
   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 * custom configure/CMake flags, if any
  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 to open a pull request instead as discussed below.
  33
  34 Still not sure how to do? Feel free to [subscribe](https://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 optional continuous integration (CI) builds
  49    You can setup Travis CI, Cirrus CI and AppVeyor builds for your fork to
  50    test your changes on Linux, FreeBSD, macOS and Windows before opening a
  51    pull request.
  52    (See https://docs.travis-ci.com/user/tutorial/ for information
  53    on setting up Travis CI; go to https://ci.appveyor.com/login and log
  54    in with your GitHub account and select "NEW PROJECT" to set up an
  55    AppVeyor build.)
  56
  57 3) Setup your git working copy
  58    git clone https://github.com/<username>/tcpdump.git
  59    cd tcpdump
  60    git remote add upstream https://github.com/the-tcpdump-group/tcpdump
  61    git fetch upstream
  62
  63 4) Do a 'touch .devel' in your working directory.
  64    Currently, the effect is
  65    a) add (via configure, in Makefile) some warnings options ( -Wall
  66    -Wmissing-prototypes -Wstrict-prototypes, ...) to the compiler if it
  67    supports these options,
  68    b) have the Makefile support "make depend" and the configure script run it.
  69
  70 5) Configure and build
  71    ./configure && make -s && make check
  72
  73 6) Add/update tests
  74    The tests directory contains regression tests of the dissection of captured
  75    packets.  Those captured packets were saved running tcpdump with option "-w
  76    sample.pcap".  Additional options, such as "-n", are used to create relevant
  77    and reproducible output; "-#" is used to indicate which particular packets
  78    have output that differs.  The tests are run with the TZ environment
  79    variable set to GMT0, so that UTC, rather than the local time where the
  80    tests are being run, is used when "local time" values are printed.  The
  81    actual test compares the current text output with the expected result
  82    (sample.out) saved from a previous version.
  83
  84    Any new/updated fields in a dissector must be present in a sample.pcap file
  85    and the corresponding output file.
  86
  87    Configuration is set in tests/TESTLIST.
  88    Each line in this file has the following format:
  89    test-name   sample.pcap   sample.out   tcpdump-options
  90
  91    The sample.out file can be produced as follows:
  92    (cd tests && TZ=GMT0 ../tcpdump -# -n -r sample.pcap tcpdump-options > sample.out)
  93
  94    Or, for convenience, use "./update-test.sh test-name"
  95
  96    It is often useful to have test outputs with different verbosity levels
  97    (none, -v, -vv, -vvv, etc.) depending on the code.
  98
  99 7) Test with 'make check'
 100    Don't send a pull request if 'make check' gives failed tests.
 101
 102 8) Try to rebase your commits to keep the history simple.
 103    git rebase upstream/master
 104    (If the rebase fails and you cannot resolve, issue "git rebase --abort"
 105    and ask for help in the pull request comment.)
 106
 107 9) Once 100% happy, put your work into your forked repository.
 108    git push
 109    This will trigger your fork CI tests, if set up in step 2.
 110
 111 10) Initiate and send a pull request
 112     (See https://help.github.com/articles/using-pull-requests/)
 113     This will trigger the upstream repository CI tests.
 114
 115
 116 Code style and generic remarks
 117 ------------------------------
 118 a) A thorough reading of some other printers code is useful.
 119
 120 b) Put the normative reference if any as comments (RFC, etc.).
 121
 122 c) Put the format of packets/headers/options as comments if there is no
 123    published normative reference.
 124
 125 d) The printer may receive incomplete packet in the buffer, truncated at any
 126    random position, for example by capturing with '-s size' option.
 127    If your code reads and decodes every byte of the protocol packet, then to
 128    ensure proper and complete bounds checks it would be sufficient to read all
 129    packet data using the GET_*() macros, typically:
 130     GET_U_1(p)
 131     GET_S_1(p)
 132     GET_BE_U_n(p), n in { 2, 3, 4, 5, 6, 7, 8 }
 133     GET_BE_S_n(p), n in { 2, 3, 4, 5, 6, 7, 8 }
 134    If your code uses the macros above only on some packet data, then the gaps
 135    would have to be bounds-checked using the ND_TCHECK_*() macros:
 136     ND_TCHECK_n(p), n in { 1, 2, 3, 4, 5, 6, 7, 8, 16 }
 137     ND_TCHECK_SIZE(p)
 138     ND_TCHECK_LEN(p, l)
 139    For the ND_TCHECK_* macros (if not already done):
 140      Assign: ndo->ndo_protocol = "protocol";
 141      Define: ND_LONGJMP_FROM_TCHECK before including netdissect.h
 142      Make sure that the intersection of GET_*() and ND_TCHECK_*() is minimal,
 143      but at the same time their union covers all packet data in all cases.
 144    You can test the code via:
 145      sudo ./tcpdump -s snaplen [-v][v][...] -i lo # in a terminal
 146      sudo tcpreplay -i lo sample.pcap             # in another terminal
 147    You should try several values for snaplen to do various truncation.
 148
 149 e) Do invalid packet checks in code: Think that your code can receive in input
 150    not only a valid packet but any arbitrary random sequence of octets (packet
 151    - built malformed originally by the sender or by a fuzz tester,
 152    - became corrupted in transit or for some other reason).
 153    Print with: nd_print_invalid(ndo);   /* to print " (invalid)" */
 154
 155 f) Use 'struct tok' for indexed strings and print them with
 156    tok2str() or bittok2str() (for flags).
 157
 158 g) Avoid empty lines in output of printers.
 159
 160 h) A commit message must have:
 161    First line: Capitalized short summary in the imperative (70 chars or less)
 162
 163    Body: Detailed explanatory text, if necessary. Fold it to approximately
 164    72 characters. There must be an empty line separating the summary from
 165    the body.
 166
 167 i) Avoid non-ASCII characters in code and commit messages.
 168
 169 j) Use the style of the modified sources.
 170
 171 k) Don't mix declarations and code
 172
 173 l) Don't use // for comments
 174    Not all C compilers accept C++/C99 comments by default.
 175
 176 m) Avoid trailing tabs/spaces