.. _task-api-changes:

========================
Task upgrading checklist
========================

This section contains a checklist of changes to the task implementation,
updated as they get refactored over time.


2026-02
=======


Split server-side and worker-side tasks
---------------------------------------

``BaseTask`` is now ``BaseExternalTask``, which is the root of the class
hierarchy of tasks that run on external workers and signing workers.

All other tasks descend from ``DBTask``, which can assume direct access to
Django models and settings.

``BaseExternalTask`` subclasses are mirrored as external workers into the
``DBTask`` class hierarchy by way of proxy adapter classes.

See :issue:`1316`.


``build_dynamic_data`` merged into ``compute_dynamic_data``
-----------------------------------------------------------

The two functions were basically the same and have been unified into
``compute_dynamic_data``.

Due to the introduction of task input fields, ``compute_dynamic_data`` now
takes no arguments.


Introduced task input fields
----------------------------

Task input fields (see :ref:`task-input-fields`) replace
``TaskDatabaseInterface`` for database lookups in external workers.

The values of task input fields are persisted in dynamic task data
automatically, and the field values can be used worker-side directly.

You can drop from ``compute_dynamic_data`` all the code that stores artifact
IDs and environment IDs, and change the rest of the task code to use the fields
directly.


Removed ``build_architecture()``
--------------------------------

The ``build_architecture()`` method has been removed in favour of a task input
field.

A missing value for a task architecture is not filled with the worker
architecture anymore, but with a server-defined fallback value.

See :issue:`1347`.


Unified data model for sending lookup results to external clients
-----------------------------------------------------------------

``ArtifactInfo`` and ``MultipleArtifactInfo`` have been merged into
``InputArtifactSingle`` and ``InputArtifactMultiple``, and ``CollectionInput``
is now ``InputCollectionSingle``.

``Input*`` structures now also contain artifact and collection data.


Separate methods for computing subject and configuration context
----------------------------------------------------------------

Task configuration for a task can now be looked up without computing its
dynamic data.

Those values are now computed using
``DBTask.get_task_configuration_subject_context``, which for external workers
calls ``BaseExternalTask.get_subject`` and
``BaseExternalTask.get_configuration_context``.

These ``BaseExternalTask`` methods can rely on all input fields marked with
``stage=Stage.CONFIG`` to be successfully resolved.


Tag based scheduling
--------------------

New methods have been added to compute tags for tag-based scheduling.

To recap:

* Tasks can provide tags to workers
* Tasks can require tags from workers
* Workers can provide tags to tasks
* Workers can require tags from tags

These new methods have been added:

* ``DBTask.get_provided_worker_tags``, classmethod, runs on worker. Hook for
  the task class to contribute to worker-provided tags.
* ``DBTask.compute_system_required_tags``, runs when the task becomes pending.
  Contribute task-required tags, with the ``system`` provenance.
* ``DBTask.get_user_provided_tags``, runs when the task becomes pending.
  Contribute task-required tags, with the ``user`` provenance.
* ``DBTask.compute_system_provided_tags``, runs when the task becomes pending.
  Contribute task-provided tags, with the ``system`` provenance.

* ``BaseExternalTask.get_provided_worker_tags``, classmethod, runs on worker. Hook for
  the task class to contribute to worker-provided tags.
* ``BaseExternalTask.compute_system_required_tags``, runs when the task becomes pending.
  Contribute task-required tags, with the ``system`` provenance.
* ``BaseExternalTask.get_user_provided_tags``, runs when the task becomes pending.
  Contribute task-required tags, with the ``user`` provenance.
* ``BaseExternalTask.compute_system_provided_tags``, runs when the task becomes pending.
  Contribute task-provided tags, with the ``system`` provenance.

For worker tasks, the results of the ``BaseExternalTask`` methods are added to
those of the corresponding ``DBTask`` methods.