Architecture decision log

Design tenets

1. Simple things should be easy, complex things should be possible.
2. Configuration errors should be easy to debug with clear error messages and documentation. The user shouldn't have to deal with stack traces.
3. Configuration closest to where an object is defined should have the highest precedence when influencing that object

Architecture Decisions

2024.01.02 - Precedence of environment variables in included task files

Context

The include global config allows additional options and tasks to be loaded from other files. This includes the env and envfile global options, which then have to be prioritised in some way relative to other sources of environment variables.

Decisions

1. env and envfile options are merged across all files, and then applied to all tasks the same

   • This means tasks defined in the same file as a global env object will still use environment variables from the root tasks file with higher precedence
   • This avoids a surprising situation where overriding a task in the main task file would cause that task to reference different different env vars
   • It also avoids potentially making it impossible to directly override env vars of tasks from included files
   • It is still possible to use env files to define environment variables differently for different tasks, but it requires naming those variables differently in the env file, then mapping them to the required variable at the task level (considering design tenet 1)

2. The env option has higher precedence than envfile from the same context

   • This is controversial considering the discussion here on #129, but necessary for consistency, both for historical reasons and to respect design tenet 3.