alunduil / alunduil/blog.alunduil.com

Workflows are consolidated by trigger and follow the when/what naming convention

Open
#390 0 comments 0 reactions 0 assignees View on GitHub
enhancement
Dominant language
Astro
Stars
1
Forks
1
Avg merge
6h 34m
Merged PRs (30d)
118

Description

## Summary

Fold every workflow that gates a pull request into one file, and rename each
workflow and job to the trigger/outcome ("when / what") convention, so each
check context is unique repo-wide and stable enough to pin as a required
status check.

## Motivation

#255 asked only for distinct job names — `bats.yml`, `lychee.yml`, and
`pre-commit.yml` each keyed their job `run`, collapsing to one ambiguous
context. Working it surfaced two things that issue doesn't cover:

- Those three files have identical `on:` and `permissions:`, so the split is
incidental (each landed in its own PR), not driven by any divergence. Same
finding as alunduil/alunduil-infrastructure#265.
- `astro.yml` and `pages.yml` both name a job `build`. They fire on different
events so they never collide on one commit, but the ruleset on `main` pins the
bare context `build`; on a push to `main` that resolves against `pages.yml`'s
build rather than the pull-request build.

The convention was worked out in alunduil/woodland-generators#383 and is being
applied there in alunduil/woodland-generators#384;
alunduil/alunduil-chezmoi#413 codifies it globally. This is the blog's
application.

## Scope

- Consolidate `bats.yml`, `lychee.yml`, `pre-commit.yml`, and `astro.yml` into
one `ci.yml` on `pull_request`, one job each.
- Drop the `push` to `main` trigger. `main` takes changes only through a pull
request under strict required checks, so those runs re-tested a tree the pull
request had already tested. External link rot is the exception, and merge
cadence never suited it — #242 tracks moving that to a schedule.
- Apply the convention: workflow `name:` is the trigger/cadence (or the subject
for a single-purpose file); job `id` is the kebab wiring identifier; job
`name:` is the outcome as a human-readable phrase, unique repo-wide and
legible standalone.
- Document the convention in `CLAUDE.md` — the Portability section keeps
durable conventions in-repo, since web sessions load neither the global guide
nor host memory.

Resulting contexts:

| Workflow | Job id | Check context |
| --- | --- | --- |
| CI | `pre-commit` | Lint and format |
| CI | `bats` | Test skill scripts |
| CI | `lychee` | Check links |
| CI | `build` | Build the site |
| Pages | `build` | Build for deploy |
| Pages | `publish` | Deploy to GitHub Pages |
| Labels | `ideas` | Label idea issues |

## Acceptance criteria

- [ ] Workflows sharing a trigger live in one file as separate jobs; those that
diverge stay split, with the reason recorded inline
- [ ] Every job `name:` is a human-readable outcome phrase, unique repo-wide,
and distinct from its `id`
- [ ] No workflow/job name stutter, and no bare `build`/`test`/`check`/
`validate` context
- [ ] The convention is documented in `CLAUDE.md`
- [ ] `pre-commit run --all-files` passes

## Additional context

Supersedes #255 — that issue's narrower rename is subsumed here, and landing it
first would publish a context set this issue immediately changes.

The context rename is coordinated: the ruleset on `main` pins `build` today, and
a required context that never reports blocks merges. Tracked separately.

`alunduil-chezmoi`'s ADR 0002 ("Keep one workflow per sensor") points the other
way, but its load-bearing argument — GitHub filters `paths:` per workflow, not
per job — doesn't apply here: no blog workflow uses `paths:`.

Contributor guide

No contributing guide indexed for this repository

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.