#59 checkpkg result output ambiguous

[Sebastian Kayser]

In our efforts to lower the barrier for new maintainers, I just approached the output of a checkpkg run in a naive way (simulating a beginner) and read it from top to bottom to see whether I could make sense out of it. Feedback and suggestions below.

checkpkg output

INFO:root:Stuffing the candies under the pillow...
100% |###################################|
CSWpy-irclib:

 * Package CSWpy-irclib does not contain any binaries. Consider making it
   ARCHALL = 1 instead of sparc. However, be aware that there might be other
   reasons to keep it architecture-specific.

# Checkpkg suggests adding the following lines to the GAR recipe:
# This is a summary; see above for details.
ARCHALL_CSWpy-irclib = 1
If any of the reported errors were false positives, you can override them
pasting the lines below to the GAR recipe.
CHECKPKG_OVERRIDES_CSWpy-irclib += pkginfo-opencsw-repository-uncommitted
CHECKPKG_OVERRIDES_CSWpy-irclib += wrong-docdir|expected=/opt/csw/shared/doc/py_irclib/...|in-package=/opt/csw/share/doc/py_python_irclib/license
Please note that checkpkg isn't suggesting you should simply add these overrides
do the Makefile.  It only informs what the overrides could look like.  You need
to understand what are the reported issues about and use your best judgement to
decide whether to fix the underlying problems or override them. For more
information, scroll up and read the detailed messages.
gmake: *** [pkgcheck] Error 2

Feedback / suggestions

• The archall description and suggestion are excellent!
• Just after ARCHALL, the override section starts less clear and as a whole seems to deal with different issues (is this the case?)
• "If any of the reported errors were false positivies": Which errors? "were" so must be related to the ones above? But none of them are related to the overrides.
• Okay, so if not above, must be the ones below. But these are only overrides?
• What do the overrides want to tell me? Could they provide an explanation as ARCHALL above?

If there's really a difference between the two sorts of outputs (ARCHALL vs. overrides) which is not easy to address, a reworded introduction to the overrides section along with a link to the checkpkg error tags page on the wiki might be an easy fix to make it more self-explaining to a new user.

[wahwah]

On the technical level, one problem is that some output comes from print statements, and some output comes from templates. The templates are in the source:csw/mgar/gar/v2/lib/python/checkpkg_lib.py#L43 file, print statements elsewhere.

The overrides are provided in a separate block / data structure, I'm not sure it's easy to add explanations to that section.

There are 3 kinds of messages:

• error tags
• things to print ("messages")
• GAR suggestion lines

These 3 are combined to produce the output. Which of the three are emitted, is decided by individual checks. For example, the ARCHALL thing is a message and a GAR suggestion line, and not an error (hence no overrides). On the other hand, the wrong-docdir thing is an error, and the check function did not return any message with it.

The output as a whole depends on both things - how the report is formatted, and what messages individual check functions are emitting. To improve the output, both sides would need to be improved.

[Sebastian Kayser]

Thanks for the explanation, makes sense now. For comparison purposes, the output below is an example for where the overall output is more coherent. All overrides (except uncomitted) have corresponding messages. I'll think about an amendment to the explanatory output sections to make them clearer in the initial case above.

CSWstunnel:

 * File root/opt/csw/share/doc/stunnel/changelog contains bad content:
   '/usr/local'. If it's a legacy file you can't modify, or if you
   investigated the issue and the string does not pose a real issue, you can
   override this error.
 * Dependency issues of CSWstunnel:
 * CSWlibwrap1 is needed by CSWstunnel, because:
 *  - opt/csw/bin/stunnel needs the libwrap.so.1 soname
 *  - opt/csw/lib/stunnel/libstunnel.so needs the libwrap.so.1 soname
 * RUNTIME_DEP_PKGS_CSWstunnel += CSWlibwrap1
 * CSWlibz1 is needed by CSWstunnel, because:
 *  - opt/csw/lib/stunnel/libstunnel.so needs the libz.so.1 soname
 *  - opt/csw/bin/stunnel needs the libz.so.1 soname
 * RUNTIME_DEP_PKGS_CSWstunnel += CSWlibz1
 * If you don't know of any reasons to include these dependencies, you might
   remove them:
 * ? CSWtcpwrap
 * ? CSWzlib

# Checkpkg suggests adding the following lines to the GAR recipe:
# This is a summary; see above for details.
RUNTIME_DEP_PKGS_CSWstunnel += CSWlibwrap1
RUNTIME_DEP_PKGS_CSWstunnel += CSWlibz1
If any of the reported errors were false positives, you can override them
pasting the lines below to the GAR recipe.
CHECKPKG_OVERRIDES_CSWstunnel += pkginfo-opencsw-repository-uncommitted
CHECKPKG_OVERRIDES_CSWstunnel += file-with-bad-content|/usr/local|root/opt/csw/share/doc/stunnel/changelog
CHECKPKG_OVERRIDES_CSWstunnel += missing-dependency|CSWlibwrap1
CHECKPKG_OVERRIDES_CSWstunnel += missing-dependency|CSWlibz1
CHECKPKG_OVERRIDES_CSWstunnel += surplus-dependency|CSWzlib
CHECKPKG_OVERRIDES_CSWstunnel += surplus-dependency|CSWtcpwrap
Please note that checkpkg isn't suggesting you should simply add these overrides
do the Makefile.  It only informs what the overrides could look like.  You need
to understand what are the reported issues about and use your best judgement to
decide whether to fix the underlying problems or override them. For more
information, scroll up and read the detailed messages.
gmake: *** [pkgcheck] Error 2

[wahwah]

The ARCHALL line is not typical in that there is a GAR suggestion line without a message and without an associated error. I think that most of the readability issues could be solved by going over the checks and e.g. adding messages to checks that only emit errors.

[wahwah]

• status changed from new to assigned

[15993] is an example of a change that adds a message to a check which previously only emitted error tags.