.. workflow:: update_suites

Workflow ``update_suites``
==========================

This workflow does whatever is needed to coordinate metadata updates for all
archives in a :ref:`workspace <explanation-workspaces>`.  Initially this
will just involve generating basic indexes for each of the suites in those
archives that have been changed, but later it may also generate
supplementary files such as ``Contents-*``.

This workflow has the :ref:`well-known <workflow-well-known>` template name
"update-suites".

The workflow operates on the workspace in which it was created.  It does
nothing if that workspace does not have a (singleton)
:collection:`debian:archive` collection.

To begin with, this workflow can just be run periodically, although that
will not scale well to large numbers of suites.  We should eventually have a
mechanism where changes to a collection can trigger a workflow.

Only owners of the corresponding workspace may run this workflow.

* ``task_data``:

  * ``force_basic_indexes`` (boolean, defaults to False): if True,
    regenerate basic indexes (``Packages``, ``Sources``, ``Release``, and
    their variants) even if the state of the archive does not seem to have
    changed since they were last generated
  * ``only_suites`` (list of strings, optional): if set, limit updates to
    suites with these names

Key generation stage
--------------------

If the archive does not have ``signing_keys`` set in its data, then the
workflow first creates a :task:`GenerateKey` task, with task data as
follows:

* ``purpose``: ``openpgp``
* ``description``: a suitable description of the new key, identifying the
  workspace

It then creates a :ref:`workflow callback <workflow-callback>` with ``step``
set to ``generated-key`` and a dependency on the :task:`GenerateKey` task.
When called, that callback sets the ``signing_keys`` field in the archive's
data to be a list containing only the fingerprint of the new
:asset:`debusine:signing-key` asset.

Main stage
----------

The workflow creates an :workflow:`update_suite` sub-workflow for each suite
that it considers to need updating, with task data as follows:

* ``suite_collection``: the suite whose indexes should be generated

If the key generation stage above created a :task:`GenerateKey` task, then
it adds the associated workflow callback as an additional dependency of each
:workflow:`update_suite` sub-workflow.

.. todo::

    `Valid-Until
    <https://wiki.debian.org/DebianRepository/Format#Date.2C_Valid-Until>`__
    can be supported by adding a field to the suite collection specifying
    the validity period.  This workflow would then additionally include all
    those whose validity period is nearly up in its search criteria.
