HACKING: add chapter on checkpatch

Include hints on how to skip some of the tests in some really
exceptional case.

Note: the file includes an example of commit message with a signed
off tag that triggers a checkpatch error.
Let checkpatch to ignore BAD_SIGN_OFF error.

Checkpatch-ignore: BAD_SIGN_OFF
Change-Id: I05bf0ab8008649f3f9b38452e056dc3df83a1a4f
Signed-off-by: Antonio Borneo <borneo.antonio@gmail.com>
Reviewed-on: https://review.openocd.org/c/openocd/+/5609
Tested-by: jenkins

diff --git a/HACKING b/HACKING
index 96b05f2d62b20e41818726e977ce406743f68069..be5699990e0ebc65b43f1928c573b011f3250efa 100644 (file)
--- a/HACKING
+++ b/HACKING
@@ -171,6 +171,8 @@ while(!done) {
 @endcode
    \note use "git add ." before commit to add new files.
 
+   \note check @ref checkpatch for hint about checkpatch script
+
    Commit message template, notice the short first line.
    The field '<c>specify touched area</c>'
    should identify the main part or subsystem the patch touches.
@@ -179,7 +181,9 @@ specify touched area: short comment
 <blank line>
 Longer comments over several lines, explaining (where applicable) the
 reason for the patch and the general idea the solution is based on,
-any major design decisions, etc...
+any major design decisions, etc. Limit each comment line's length to 75
+characters; since 75 it's too short for a URL, you can put the URL in a
+separate line preceded by 'Link: '.
 <blank line>
 Signed-off-by: ...
 @endcode
@@ -227,6 +231,65 @@ git push review
 
 Further reading: http://www.coreboot.org/Git
 
+@section checkpatch About checkpatch script
+
+OpenOCD source code includes the script checkpatch to let developers to
+verify their patches before submitting them for review (see @ref gerrit).
+
+Every patch for OpenOCD project that is submitted for review on Gerrit
+is tested by Jenkins. Jenkins will run the checkpatch script to analyze
+each patch.
+If the script highlights either errors or warnings, Gerrit will add the
+score "-1" to the patch and maintainers will probably ignore the patch,
+waiting for the developer to send a fixed version.
+
+The script checkpatch verifies the SPDX tag for new files against a very
+short list of license tags.
+If the license of your contribution is not listed there, but compatible
+with OpenOCD license, please alert the maintainers or add the missing
+license in the first patch of your patch series.
+
+The script checkpatch has been originally developed for the Linux kernel
+source code, thus includes specific tests and checks related to Linux
+coding style and to Linux code structure. While the script has been
+adapted for OpenOCD specificities, it still includes some Linux related
+test. It is then possible that it triggers sometimes some <em>false
+positive</em>!
+
+If you think that the error identified by checkpatch is a false
+positive, please report it to the openocd-devel mailing list or prepare
+a patch for fixing checkpatch and send it to Gerrit for review.
+
+\attention The procedure below is allowed only for <em>exceptional
+cases</em>. Do not use it to submit normal patches.
+
+There are <em>exceptional cases</em> in which you need to skip some of
+the tests from checkpatch in order to pass the approval from Gerrit.
+
+For example, a patch that modify one line inside a big comment block
+will not show the beginning or the end of the comment block. This can
+prevent checkpatch to detect the comment block. Checkpatch can wrongly
+consider the modified comment line as a code line, triggering a set of
+false errors.
+
+Only for <em>exceptional cases</em>, it is allowed to submit patches
+to Gerrit with the special field 'Checkpatch-ignore:' in the commit
+message. This field will cause checkpatch to ignore the error types
+listed in the field, only for the patch itself.
+The error type is printed by checkpatch on failure.
+For example the names of Windows APIs mix lower and upper case chars,
+in violation of OpenOCD coding style, triggering a 'CAMELCASE' error:
+@code
+CHECK:CAMELCASE: Avoid CamelCase: <WSAGetLastError>
+#96105: FILE: src/helper/log.c:505:
++       error_code = WSAGetLastError();
+@endcode
+Adding in the commit message of the patch the line:
+@code
+Checkpatch-ignore: CAMELCASE
+@endcode
+will force checkpatch to ignore the CAMELCASE error.
+
 @section timeline When can I expect my contribution to be committed?
 
 The code review is intended to take as long as a week or two to allow