debusine:task-configuration

# Category `debusine:task-configuration`

This bare data item represents overrides that can be applied to task configuration.

It has two sets of fields: some that define when the overrides should be applied, and some that define the overrides themselves.

- Data used to identify where the configuration is applied:

  - `task_type` (required if `template` is None): the `task_type` of the task for which we want to provide default values and overrides

  - `task_name` (required if `template` is None): the `task_name` of the task for which we want to provide default values and overrides

  - `subject` (defaults to None): an abstract string value representing the subject of the task (i.e. something passed as input). It is meant to group possible inputs for the tasks into groups that we expect to configure similarly.

  - `context` (defaults to None): an abstract string value representing the configuration context of the task. It is typically another important task parameter (or derived from it).

  - `tags_provided` (defaults to `[]`): a list of tags that the task must provide, or a string with a boolean tag expression matching the tags that the task must provide

  - `tags_required` (defaults to `[]`): a list of tags that the task must require, or a string with a boolean tag expression matching the tags that the task must require

  - `template` (defaults to None): the name of a template entry

Constraints:

> - When `template` is set, `task_type`, `task_name`, `subject` and `context` should be None

- Data representing the actions to perform on the matching task configuration data (all fields are optional):

  - `use_templates` (list): a list of template names whose corresponding entries shall be retrieved and imported as part of the configuration returned for the current entry

  - `delete_values` (list): a list of configuration keys to delete from the values returned by the previous configuration levels

  - `default_values` (dict): values to use as default values if the user did not provide any value for the given configuration keys

  - `override_values` (dict): values to use even if the user did provide a value for the given configuration key

  - `lock_values` (list): a list of configuration keys that should be locked (i.e. next configuration level can no longer provide or modify the corresponding value)

  - `provide_tags` (list): a list of additional tags to add to task-provided tags, using the `workspace` provenance

  - `require_tags` (list): a list of additional tags to add to task-required tag, using the `workspace` provenances

  - `comment` (string): multiline free form text used to document the reasons behind the provided configuration. Text can use Markdown syntax.

This mechanism only allows to control top-level configuration keys in `task_data` fields. It is not possible to override a single value in a nested dictionary, but you can override the whole dictionary if you wish so.

When the same configuration key appears in `default_values` and `override_values` (either in a single entry, or in the entry created by combining the different levels), the one from `override_values` take precedence over the one from `default_values`.