Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Tiers and scans

A repository’s authors watch a few of its dependencies closely and the rest less often. headwater looks often for the first and less often for the rest, and the authors say which is which.

Tiers

A tier is a named set of a repository’s dependencies, with a cadence. Every dependency of a repository state belongs to exactly one tier (13), and the default tier holds every dependency no other tier names. headwater reads the tiers and their cadences from the repository state (14), through each dependency description’s answer of the tiers, each with its cadence and the identities it names (41). headwater never moves a dependency between tiers and never changes a cadence. The authors decide both, in the repository, where a change to them lands like any other change.

The first profile reads the tiers from .config/headwater.toml: each tier’s name, its cadence and the identities it names. A repository with no such file has the default tier alone, with a cadence of seven days (C.2).

Cadence and due

A tier’s cadence is the longest time it may go without a complete scan while scans are asked for. headwater runs no schedule of its own: an asker asks, at a session’s start, on a timer or by hand, and the cadence decides how much of each scan reaches a source.

A scan is one reading of a repository state’s dependencies and of the sources of those in the tiers it covers. It is complete for a tier when every dependency of the tier was read and every source reached. A tier is due when its cadence has passed since its last complete scan, or when it has never had one.

A scan of what is due reaches the sources of the due tiers’ dependencies and of no others (15). A scan of a named tier reaches its sources whether or not it is due. A session that starts every hour and asks for what is due reaches a source only when a tier’s cadence has passed.

An incomplete scan

A scan that leaves a tier incomplete reports every dependency it could read, reports the rest as unread with the reason, and leaves the tier due (16). A source that cannot be reached costs its own dependencies and nothing else: the scan reports the tier’s other dependencies, and the next scan of what is due tries again (S3).

ONE TIER, CADENCE THREE DAYS fresh due fresh due day 0 1 2 3 4 5 6 7 8 9 complete scan incomplete scan complete scan asked what it holds no source reached (17) one source unreached, still due (16) days
A tier is due when its cadence has passed since its last complete scan, or when it has never had one. An incomplete scan leaves it due (16), and asking what headwater holds reaches no source and writes nothing (17).

Asking what headwater holds

Asking what headwater holds reaches no source and writes nothing (17). The answer is the newest report for each tier, and says when each was made and whether its tier is due. A scan of what is due, asked when no tier is due, reaches no source either. A session that starts again an hour after its first is told the same releases and when they were found (S2).

Still to rule: questions 2, 14, 15, 16, 18, 19 and 20, and the statement’s own question on when a cadence starts, in Open questions.