doc: development_process: document that CI style checks can fail

The CI style checking solution can produce false positives when it's
given code that it mis-parses, or that follows conventions it doesn't
allow.  Document a couple examples, and explicitly note that
maintainers should override the -1 vote if they're encountered.

For those following along in the commit history:

   static uint8_t __aligned(PAGE_SIZE) page_pool[PAGE_SIZE * POOL_PAGES];

checkpatch sees "uint8_t __aligned(PAGE_SIZE)" and infers a prototype
for a function "__aligned" that takes an unnamed parameter of type
"PAGE_SIZE".  So it adds "PAGE_SIZE" as a known type name.

   IOPCTL_Type *base = config->base;

This is common in driver code where the vendor HAL allows typedefs for
structure types.  checkpatch was designed for an environment with
limited use of typedefs; "struct IPCTL_Type" would have been handled
properly.

Signed-off-by: Peter Bigot <peter.bigot@nordicsemi.no>
This commit is contained in:
Peter Bigot 2020-07-21 15:04:14 -05:00 committed by Carles Cufí
commit f45f72c9a4

View file

@ -210,7 +210,7 @@ Developers are expected to fix issues and rework their patches and submit again.
The CI infrastructure currently runs the following tests:
- Run ''checkpatch'' for code style issues (can vote -1 on errors)
- Run ''checkpatch'' for code style issues (can vote -1 on errors; see note)
- Gitlint: Git commit style based on project requirements
- License Check: Check for conflicting licenses
- Run ''sanitycheck'' script
@ -220,6 +220,25 @@ The CI infrastructure currently runs the following tests:
- Verify documentation builds correctly.
.. note::
''checkpatch'' is a Perl script that uses regular expressions to
extract information that requires a C language parser to process
accurately. As such it sometimes issues false positives. Known
cases include constructs like::
static uint8_t __aligned(PAGE_SIZE) page_pool[PAGE_SIZE * POOL_PAGES];
IOPCTL_Type *base = config->base;
Both lines produce a diagnostic regarding spaces around the ``*``
operator: the first is misidentifed as a pointer type declaration
that would be correct as ``PAGE_SIZE *POOL_PAGES`` while the second
is misidentified as a multiplication expression that would be correct
as ``IOPCTL_Type * base``.
Maintainers can override the -1 in cases where the CI infrastructure
gets the wrong answer.
.. _gh_labels: