HACKING: document practices to improve code quality

Change-Id: I58a7d978b7d5bca3037c4535f06746b9f4411950
Signed-off-by: Paul Fertser <fercerpav@gmail.com>
Reviewed-on: http://openocd.zylin.com/4343
Tested-by: jenkins
This commit is contained in:
Paul Fertser 2018-01-16 15:11:18 +03:00 committed by Matthias Welwarsky
parent 70b15f989f
commit 6e356cbfe2
1 changed files with 50 additions and 4 deletions

54
HACKING
View File

@ -29,12 +29,58 @@ The procedure to create a patch is essentially:
- correct the patch and re-send it according to review feedback - correct the patch and re-send it according to review feedback
Your patch (or commit) should be a "good patch": focus it on a single Your patch (or commit) should be a "good patch": focus it on a single
issue, and make it be easily reviewable. Don't make issue, and make it easily reviewable. Don't make
it so large that it's hard to review; split large it so large that it's hard to review; split large
patches into smaller ones. (That can also help patches into smaller ones (this will also help
track down bugs later on.) All patches should to track down bugs later). All patches should
be "clean", which includes preserving the existing be "clean", which includes preserving the existing
coding style and updating documentation as needed. coding style and updating documentation as needed. When adding a new
command, the corresponding documentation should be added to
@c doc/openocd.texi in the same commit. OpenOCD runs on both Little
Endian and Big Endian hosts so the code can't count on specific byte
ordering (in other words, must be endian-clean).
There are several additional methods of improving the quality of your
patch:
- Runtime testing with Valgrind Memcheck
This helps to spot memory leaks, undefined behaviour due to
uninitialized data or wrong indexing, memory corruption, etc.
- Clang Static Analyzer
Using this tool uncovers many different kinds of bugs in C code,
with problematic execution paths fully explained. It is a part of
standard Clang installation.
To generate a report, run this in the OpenOCD source directory:
@code
mkdir build-scanbuild; cd build-scanbuild
scan-build ../configure
scan-build make CFLAGS="-std=gnu99 -I. -I../../jimtcl"
@endcode
- Runtime testing with sanitizers
Both GCC and LLVM/Clang include advanced instrumentation options to
detect undefined behaviour and many kinds of memory
errors. Available with @c -fsanitize=* command arguments.
Example usage:
@code
mkdir build-sanitizers; cd build-sanitizers
../configure CC=clang CFLAGS="-fno-omit-frame-pointer \
-fsanitize=address -fsanitize=undefined -ggdb3"
make
export ASAN_OPTIONS=detect_stack_use_after_return=1
src/openocd -s ../tcl -f /path/to/openocd.cfg
@endcode
Please consider performing these additonal checks where appropriate
(especially Clang Static Analyzer for big portions of new code) and
mention the results (e.g. "Valgrind-clean, no new Clang analyzer
warnings") in the commit message.
Say in the commit message if it's a bugfix (describe the bug) or a new Say in the commit message if it's a bugfix (describe the bug) or a new
feature. Don't expect patches to merge immediately feature. Don't expect patches to merge immediately