.. collection:: debian:qa-results

Category ``debian:qa-results``
------------------------------

This collection can host all the QA results for all the packages in a
given suite. We thus have different kind of items for each QA task.

Common features across all QA results
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

The name of the collection item is always
``{task_name}_{package}_{version}_{architecture}_{work_request_id}``
substituting values from the per-item data described below.

* Variables when adding items: see "Per-item data" below

* Data:

  * ``suite_collection`` (:ref:`lookup-single`, required): the
    :collection:`debian:suite` collection for which the collection is
    storing the QA results.
  * ``old_items_to_keep``: number of old items to keep. Defaults to 5.
    For each task/package/architecture combination, the collection always
    keeps the given number of most recent entries (based on the
    ``timestamp`` field). The cleanup is automatically done when adding
    new items.

    .. note::

        At some point, we may need more advanced logic than this, for
        instance to clean up QA results about packages that are gone
        from the corresponding suite.

* Per-item data:

  * ``task_name`` (inferred from work request when adding item): the name of
    the task that generated the QA result (so ``autopkgtest``, ``lintian``,
    ``piuparts``, ``blhc``)
  * ``package``: the name of the source package being analyzed, or the
    source package from which the binary package being analyzed was built
  * ``version``: the version of the source package being analyzed, or the
    source package from which the binary package being analyzed was built
  * ``architecture``: ``source`` for a source analysis, or the appropriate
    architecture name for a binary analysis
  * ``timestamp``: a Unix timestamp (cf. ``date +%s``) used to estimate
    the freshness of the QA result, can often be usefully tied to the
    ``Date`` field of the package repository in which the analysis was
    performed.
  * ``work_request_id``: the ID of the WorkRequest that generated
    the QA result
  * ``result`` (inferred from work request when adding item): duplicates the
    string value of the result field of the associated WorkRequest

* Lookup names:

  * ``latest:TASKNAME_PACKAGE_ARCHITECTURE``: the latest QA result for tasks
    named ``TASKNAME`` for the source package named ``PACKAGE`` on
    ``ARCHITECTURE``.

Specification for ``lintian``
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

The collection item is a :artifact:`debian:lintian` artifact. The collection
contains items for the source and for all architectures.

A lintian analysis is outdated if:

* either the underlying source or binary packages are outdated (i.e. have
  different version numbers) compared to what's available in the
  :collection:`debian:suite` collection
* or the lintian version used to perform the analysis is older than the
  version available in the :collection:`debian:suite` collection

Specification for ``autopkgtest``
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

The collection item is a :artifact:`debian:autopkgtest` artifact. The
collection contains items for all architectures (but not for the source).

An autopkgtest analysis is outdated if:

* either the underlying source or binary packages are outdated (i.e. have
  different version numbers) compared to what's available in the
  :collection:`debian:suite` collection
* or the timestamp of the analysis is older than 30 days compared
  to the ``Date`` timestamp of the :collection:`debian:suite` collection

Specification for ``piuparts``
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

The collection item is a bare data item of category
:bare-data:`debian:qa-result` with all the common per-item data described
above. The collection contains items for all architectures (but not for the
source).

A piuparts analysis is outdated if the underlying binary packages are
outdated (i.e. have different version numbers) compared to what's available
in the :collection:`debian:suite` collection.

.. note::

   The lack of piuparts artifact means that we don't have any information
   about the binary packages that were analyzed except if we lookup the
   details of the WorkRequest. That's probably going too far so instead
   we will likely compare based on the source version documented in the
   per-item data.

   Filed :issue:`805` to think about introducing a proper artifact at some
   point.

Specification for ``blhc``
~~~~~~~~~~~~~~~~~~~~~~~~~~

The collection item is a :artifact:`debian:blhc` artifact. The collection
contains items for all architectures (but not for the source).

A blhc analysis is outdated if the underlying source package is
outdated (i.e. has a different version number) compared to what's available
in the :collection:`debian:suite` collection. The comparison needs to be
performed based on the metadata of the linked
:artifact:`debian:package-build-log` artifact.

Specification for ``debdiff``
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

The :task:`DebDiff` QA task does not contribute any item to the
``debian:qa-results`` because it does not provide any validation
of a single target artifact.

By its nature, the task already performs a comparison between
the original version and the new version. And the result of the comparison
can't easily be used to draw any conclusion about the update, it
is up to human reviewers to decide of that.