.. workflow:: piuparts

Workflow ``piuparts``
=====================

This workflow schedules ``piuparts`` checks for binaries built by a single
source package on a set of architectures.

* ``task_data``:

  * ``prefix`` (string, optional): prefix this string to the item names
    provided in the internal collection
  * ``reference_prefix`` (string, optional unless
    ``enable_regression_tracking`` is set): prefix for the item names
    provided in the internal collection in the corresponding workflow run
    for reference tests

  * ``source_artifact`` (:ref:`lookup-single`, required): the
    :artifact:`debian:source-package` or :artifact:`debian:upload` artifact
    that built the binaries to be tested
  * ``binary_artifacts`` (:ref:`lookup-multiple`, required): see
    :task:`Piuparts`

  * ``qa_suite`` (:ref:`lookup-single`, optional unless
    ``enable_regression_tracking`` is True or ``update_qa_results`` is
    either ``yes`` or ``force``): the :collection:`debian:suite` collection
    that reference tests are being run against to detect regressions
  * ``reference_qa_results`` (:ref:`lookup-single`, optional unless
    ``enable_regression_tracking`` is True or ``update_qa_results`` is
    either ``yes`` or ``force``): the :collection:`debian:qa-results`
    collection that contains the reference results of QA tasks to use to
    detect regressions
  * ``enable_regression_tracking`` (boolean, defaults to False): configure
    the workflow to detect and display regressions in QA results
  * ``update_qa_results`` (string, defaults to ``no``): whether to update
    reference QA results.  Allowed values are ``no``, ``yes``, and
    ``force``.  When set to ``yes``, the workflow runs QA tasks and updates
    the collection passed in ``reference_qa_results`` with the results,
    unless that collection already contains a current matching result.
    ``force`` is like ``yes``, but does not check whether the collection
    already contains a current matching result.

    For compatibility, boolean False is equivalent to ``no``, and boolean
    True is equivalent to ``yes``.

  * ``vendor`` (string, required): the distribution vendor on which to run
    tests
  * ``codename`` (string, required): the distribution codename on which to
    run tests
  * ``backend`` (string, optional): see :task:`Piuparts`
  * ``environment`` (string, optional): the environment to run piuparts in
  * ``extra_repositories`` (optional): see :task:`Piuparts`
  * ``architectures`` (list of strings, optional): if set, only run on any
    of these architecture names.
  * ``arch_all_expected_installable`` (list of strings, optional): concrete
    architectures where architecture-independent packages are expected to
    be installable. :task:`Piuparts` tasks containing architecture-independent
    packages on architectures not listed here are allowed to fail.

If ``architectures`` is provided, only architectures in that list
will be considered.

The workflow computes dynamic metadata as:

.. dynamic_data::
  :method: debusine.server.workflows.piuparts::PiupartsWorkflow.compute_dynamic_data

.. note::

   Throughout this section, the following terminology is used:

    * **concrete**: architectures other than ``all``
    * **available**: architectures that exist in the Debusine instance for the given
      ``vendor``/``codename``
    * **relevant**: architectures remaining after applying the ``architectures``
      parameter (if set)

All ``binary_artifacts`` are architecture-independent
-----------------------------------------------------

For each concrete relevant available architecture, the workflow schedules a
:task:`Piuparts` task including all binary packages.

If ``arch_all_expected_installable`` is set: :task:`Piuparts` tasks for
architectures not listed in it are allowed to fail.

At least one ``binary_artifact`` is architecture-dependent
----------------------------------------------------------

For each concrete relevant architecture for which at least one binary package exists,
the workflow schedules a :task:`Piuparts` task.

Each :task:`Piuparts` task also includes all architecture-independent binary packages.

If ``arch_all_expected_installable`` is set: :task:`Piuparts` tasks for
architectures not listed in it are allowed to fail.

Task data
---------

The workflow creates :task:`Piuparts` tasks with the following task data:

* ``input.binary_artifacts``: the subset of ``{binary_artifacts}`` that are
  for the concrete architecture or ``all``
* ``build_architecture``: the concrete architecture
* ``environment``: ``{environment}`` if specified, falling back to
  ``{vendor}/match:codename={codename}``
* ``base_tgz``: ``{vendor}/match:codename={codename}``
* ``backend``: ``{backend}``
* ``extra_repositories`` copied from the workflow task, and extended
  with overlay repositories (e.g. ``experimental``) if ``codename`` is a
  known overlay

Any of the lookups in ``input.binary_artifacts`` may result in
:bare-data:`promises <debusine:promise>`, and in that case the workflow adds
corresponding dependencies.  Binary promises must include an
``architecture`` field in their data.

.. todo::

    It would be useful to have a mechanism to control multiarch tests, such
    as testing i386 packages on an amd64 testbed.

.. todo::

    It would be useful to be able to set ``base_tgz`` separately from
    ``environment``.
