dmarx / dmarx/luria

A workflow that drifts from the shipped template is invisible

Open
#204 0 comments 0 reactions 0 assignees View on GitHub
Dominant language
Python
Stars
21
Forks
2
Avg merge
6h 33m
Merged PRs (30d)
91

Description

`template-drift` covers scaffolded record fields — "a document copied from the form starts in the wrong shape". Nothing covers the other thing `luria init` scaffolds: the workflows.

## How it showed up

`dmarx/anthology-of-the-sota`'s `pages.yml` triggered on `push: [main]`, alongside `docs.yml`. So the two raced, and Pages built the merge commit's tree while Docs was still regenerating views and concretizing merge-allocated codes on top of it.

The consequence was a site permanently one merge behind for every batch of merge-allocated documents. Five documents merged in that record's #33 were 404 on the published site until Pages was dispatched by hand; two earlier ones were live only because a later unrelated merge had happened to trigger Pages again.

**The template has been right the whole time.** `template/.github/workflows/pages.yml` ships `workflow_run: workflows: [Docs]`, with a comment that states the ordering requirement explicitly:

> The site is built from the committed views, so it builds after the job that commits them.

luria's own `pages.yml` uses the same pattern against `CI`, and its site is current. The downstream copy had simply fallen behind, and no check compares the two.

## Why it is worth a check rather than a note

A scaffolded workflow is exactly the shape `template-drift` already reasons about — a file copied from a form that the form has since moved past — and the failure mode is the same: it keeps working well enough that nobody looks. This one produced a *stale published site*, which is the failure that looks most like success from the outside. The site was up, it was green, every page it served was correct, and it was missing five documents.

## The hard part

A record's workflows are legitimately edited. This one deliberately keeps a `pull_request:` trigger the template omits, because the template's reasoning is ADR-068 — a branch carries no views of its own — and that record's branches *do* carry regenerated views. So byte comparison is wrong, and "differs from template" is not by itself a finding.

What is checkable without judgement is narrower and probably enough:

1. **Ordering.** If both a Docs-shaped workflow and a Pages-shaped one trigger on push to the default branch, they race, and the one that publishes will lose to nothing and win against the one that commits. That is a structural fact about the pair, readable from the two `on:` blocks, and it does not require knowing what the template says.
2. **A named trigger that no longer exists.** `workflow_run: workflows: [Docs]` silently never fires if the Docs workflow is renamed. The template's comment warns about this in prose, which is the shape of a check that has not been written.

(1) is the one that would have caught this. (2) is the failure the fix introduces, so it would be good to have both.

Either is a report rather than a lint, since neither is mechanically fixable without deciding what the project meant.

Contributor guide

Open the contributing guide

Research direction

Start by reading the existing template-drift check and the workflow files, especially template/.github/workflows/pages.yml and luria's pages.yml. Trace how workflow definitions are discovered and reported, then define tests for push-trigger ordering and workflow_run names that no longer exist. Done means the check reports both structural failures without comparing legitimately customized workflows byte-for-byte.

Written by the indexing model from the issue text.

Assessment

Tech stack
github-actions, python
Domain
ci-cd, devtools
Issue type
Feature
Difficulty
4/5
Estimated time
3-5 days
Activity status
Active
Clarity
Mostly clear
Newbie friendliness
56/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.