refine the feedback guidelines

Provide better detailed guidelines in CONTRIBUTING and update a number
of other files to refer to that file so that the directions are now
more uniform.

1 files changed, 55 insertions, 7 deletions

diff --git a/CONTRIBUTING b/CONTRIBUTING
index 5d3b46e0..186583ed 100644
--- a/CONTRIBUTING
+++ b/CONTRIBUTING
@@ -3,6 +3,44 @@ Some Information for Contributors
 You want to contribute to Tcpdump, Thanks!
 Please, read these lines.
 
+
+How to report bugs and other problems
+-------------------------------------
+To report a security issue (segfault, buffer overflow, infinite loop, arbitrary
+code execution etc) please send an e-mail to security@tcpdump.org, do not use
+the bug tracker!
+
+To report a non-security problem (failure to compile, incorrect output in the
+protocol printout, missing support for a particular protocol etc) please check
+first that it reproduces with the latest stable release of tcpdump and the latest
+stable release of libpcap. If it does, please check that the problem reproduces
+with the current git master branch of tcpdump and the current git master branch of
+libpcap. If it does (and it is not a security-related problem, otherwise see
+above), please navigate to https://github.com/the-tcpdump-group/tcpdump/issues
+and check if the problem has already been reported. If it has not, please open
+a new issue and provide the following details:
+
+* tcpdump and libpcap version (tcpdump --version)
+* operating system name and version and any other details that may be relevant
+  (uname -a, compiler name and version, CPU type etc.)
+* configure flags if any were used
+* statement of the problem
+* steps to reproduce
+
+Please note that if you know exactly how to solve the problem and the solution
+would not be too intrusive, it would be best to contribute some development time
+and open a pull request instead as discussed below.
+
+Still not sure how to do? Feel free to [subscribe](http://www.tcpdump.org/#mailing-lists)
+to the mailing list tcpdump-workers@lists.tcpdump.org and ask!
+
+
+How to add new code and to update existing code
+-----------------------------------------------
+
+0) Check that there isn't a pull request already opened for the changes you
+   intend to make.
+
 1) Fork the Tcpdump repository on GitHub from
    https://github.com/the-tcpdump-group/tcpdump
    (See https://help.github.com/articles/fork-a-repo/)
@@ -12,8 +50,11 @@ Please, read these lines.
    on Linux and OSX before sending pull requests.
    (See http://docs.travis-ci.com/user/getting-started/)
 
-3) Clone your repository
+3) Setup your git working copy
    git clone https://github.com/<username>/tcpdump.git
+   cd tcpdump
+   git remote add upstream https://github.com/the-tcpdump-group/tcpdump
+   git fetch upstream
 
 4) Do a 'touch .devel' in your working directory.
    Currently, the effect is
@@ -47,19 +88,26 @@ Please, read these lines.
 7) Test with 'make check'
    Don't send a pull request if 'make check' gives failed tests.
 
-8) Rebase your commits against upstream/master
-   (To keep linearity)
+8) Try to rebase your commits to keep the history simple.
+   git rebase upstream/master
+   (If the rebase fails and you cannot resolve, issue "git rebase --abort"
+   and ask for help in the pull request comment.)
 
-9) Initiate and send a pull request
+9) Once 100% happy, put your work into your forked repository.
+   git push
+
+10) Initiate and send a pull request
    (See https://help.github.com/articles/using-pull-requests/)
 
-Some remarks
-------------
+
+Code style and generic remarks
+------------------------------
 a) A thorough reading of some other printers code is useful.
 
 b) Put the normative reference if any as comments (RFC, etc.).
 
-c) Put the format of packets/headers/options as comments.
+c) Put the format of packets/headers/options as comments if there is no
+   published normative reference.
 
 d) The printer may receive incomplete packet in the buffer, truncated at any
    random position, for example by capturing with '-s size' option.