.. workflow:: update_suite

Workflow ``update_suite``
=========================

This workflow updates metadata for a single :collection:`suite
<debian:suite>`.  Initially this will just involve generating and signing
basic indexes for the suite, but later it may also generate supplementary
files such as ``Contents-*``.

* ``task_data``:

  * ``suite_collection`` (:ref:`lookup-single`, required): the suite whose
    indexes should be generated

The workflow computes dynamic metadata as:

.. dynamic_data::
  :method: debusine.server.workflows.update_suite::UpdateSuiteWorkflow.compute_dynamic_data

The workflow creates a :task:`GenerateSuiteIndexes` task, with task data as
follows:

* ``suite_collection``: ``{suite_collection}``
* ``generate_at``: the transaction timestamp at which the workflow
  orchestrator is being run (this needs special care to preserve
  idempotency, since any later runs of the same workflow orchestrator would
  have a different transaction timestamp)

It then creates two :task:`SignRepositoryIndex` tasks with dependencies on
the :task:`GenerateSuiteIndexes` task.  They have task data as follows:

* ``suite_collection``: ``{suite_collection}``
* ``unsigned``: the :artifact:`debian:repository-index` artifact for the
  ``Release`` file produced by the :task:`GenerateSuiteIndexes` task
* ``mode``: ``detached`` for the first task, or ``clear`` for the second
* ``signed_name``: ``Release.gpg`` for the first task, or ``InRelease`` for
  the second

These tasks each have event reactions that add the output
:artifact:`debian:repository-index` artifact to the suite at the appropriate
path (``Release.gpg`` or ``InRelease``), setting ``created_at`` to the
transaction timestamp at which the workflow orchestrator is being run.

The ``InRelease`` task depends on the ``Release.gpg`` task, in order that
the "current" view of a suite can arrange to only show a snapshot once an
``InRelease`` file exists for it.

.. note::

    We use two tasks rather than making both signatures in a single task
    because otherwise the event reactions would have no way of
    distinguishing between the two output artifacts.
