HACKING: document practices to improve code quality 43/4343/4
authorPaul Fertser <fercerpav@gmail.com>
Tue, 16 Jan 2018 12:11:18 +0000 (15:11 +0300)
committerMatthias Welwarsky <matthias@welwarsky.de>
Mon, 9 Apr 2018 08:05:58 +0000 (09:05 +0100)
Change-Id: I58a7d978b7d5bca3037c4535f06746b9f4411950
Signed-off-by: Paul Fertser <fercerpav@gmail.com>
Reviewed-on: http://openocd.zylin.com/4343
Tested-by: jenkins

diff --git a/HACKING b/HACKING
index 0bea65a751c673f329bc5f4e2ef244e32137c96f..0d24957e141268a997274cdbb4ca0e4394e6968a 100644 (file)
@@ -29,12 +29,58 @@ The procedure to create a patch is essentially:
 - 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
-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
-patches into smaller ones. (That can also help
-track down bugs later on.) All patches should
+patches into smaller ones (this will also help
+to track down bugs later). All patches should
 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
+- 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
 feature. Don't expect patches to merge immediately

Linking to existing account procedure

If you already have an account and want to add another login method you MUST first sign in with your existing account and then change URL to read https://review.openocd.org/login/?link to get to this page again but this time it'll work for linking. Thank you.

SSH host keys fingerprints

1024 SHA256:YKx8b7u5ZWdcbp7/4AeXNaqElP49m6QrwfXaqQGJAOk gerrit-code-review@openocd.zylin.com (DSA)
384 SHA256:jHIbSQa4REvwCFG4cq5LBlBLxmxSqelQPem/EXIrxjk gerrit-code-review@openocd.org (ECDSA)
521 SHA256:UAOPYkU9Fjtcao0Ul/Rrlnj/OsQvt+pgdYSZ4jOYdgs gerrit-code-review@openocd.org (ECDSA)
256 SHA256:A13M5QlnozFOvTllybRZH6vm7iSt0XLxbA48yfc2yfY gerrit-code-review@openocd.org (ECDSA)
256 SHA256:spYMBqEYoAOtK7yZBrcwE8ZpYt6b68Cfh9yEVetvbXg gerrit-code-review@openocd.org (ED25519)
+--[ED25519 256]--+
|=..              |
|+o..   .         |
|*.o   . .        |
|+B . . .         |
|Bo. = o S        |
|Oo.+ + =         |
|oB=.* = . o      |
| =+=.+   + E     |
|. .=o   . o      |
2048 SHA256:0Onrb7/PHjpo6iVZ7xQX2riKN83FJ3KGU0TvI0TaFG4 gerrit-code-review@openocd.zylin.com (RSA)