CONTRIBUTING revision 313537
1Some Information for Contributors 2--------------------------------- 3You want to contribute to Tcpdump, Thanks! 4Please, read these lines. 5 61) 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 102) Setup an optional Travis-CI build 11 You can setup a travis build for your fork. So, you can test your changes 12 on Linux and OSX before sending pull requests. 13 (See http://docs.travis-ci.com/user/getting-started/) 14 153) Clone your repository 16 git clone https://github.com/<username>/tcpdump.git 17 184) 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 255) Configure and build 26 ./configure && make -s && make check 27 286) 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 477) Test with 'make check' 48 Don't send a pull request if 'make check' gives failed tests. 49 508) Rebase your commits against upstream/master 51 (To keep linearity) 52 539) Initiate and send a pull request 54 (See https://help.github.com/articles/using-pull-requests/) 55 56Some remarks 57------------ 58a) A thorough reading of some other printers code is useful. 59 60b) Put the normative reference if any as comments (RFC, etc.). 61 62c) Put the format of packets/headers/options as comments. 63 64d) 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 76e) 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 - built malformed originally by the sender or by a fuzz tester, 79 - became corrupted in transit). 80 Print with: ND_PRINT((ndo, "%s", istr)); /* to print " (invalid)" */ 81 82f) Use 'struct tok' for indexed strings and print them with 83 tok2str() or bittok2str() (for flags). 84 85g) Avoid empty lines in output of printers. 86 87h) A commit message must have: 88 First line: Capitalized short summary in the imperative (70 chars or less) 89 90 Body: Detailed explanatory text, if necessary. Fold it to approximately 91 72 characters. There must be an empty line separating the summary from 92 the body. 93 94i) Avoid non-ASCII characters in code and commit messages. 95 96j) Use the style of the modified sources. 97 98k) Don't mix declarations and code 99 100l) Don't use // for comments 101 Not all C compilers accept C++/C99 comments by default. 102 103m) Avoid trailing tabs/spaces 104