Continuous Integration

Estimated reading time: 6 minutes

Thirteen workflows run in this repository. Most of them you will meet on your own pull request; six run on a schedule and will reach you without your having done anything, which is the part worth reading before it happens.

This page says what each one is for and what its failure means. It does not describe how they work — the workflow files say that, and cannot drift from themselves — and it does not carry the reasoning behind a gate’s design, which lives in the design specifications.

On Your Pull Request

Workflow	What it is for
ci-tests	The suite, on every supported Python
ci-docs	Builds the documentation and runs every gate over it, including the browser demo — the same set pixi run docs-all runs locally, named by task so the two cannot diverge
ci-changelog	Checks the news fragment: that there is one, and that it is well formed
ci-citation	Validates CITATION.cff, the machine-readable record of how to cite this software. It runs only when that file changes
ci-wheels	Builds the sdist and wheel, and checks MANIFEST.in against what the sdist carries
ci-label	Labels the pull request from the paths it touches, from its branch name — a fix/… branch earns type: bug with no file needing to match — and, for dependabot[bot] and pre-commit-ci[bot], from its author
codeql	Static security analysis

Every one of these runs on every pull request except two. ci-citation is scoped to a path, so it stays quiet unless CITATION.cff itself changes. codeql is scoped to pull requests targeting main or a vA.B.x release branch, so a pull request opened against any other base does not run it.

Those same workflows run on a push to main and to a vA.B.x release branch, and ci-tests, ci-docs and ci-wheels on a v* tag besides. The release branch is in that list deliberately: a release is tagged from one (Cutting a Release), and a branch nothing checks would put the least-tested commit in the repository on PyPI. The tag is in it so that the released commit carries checks of its own rather than only the branch commit it points at.

On a Schedule

Workflow	What it is for
ci-locks	Refreshes pixi.lock weekly and opens a pull request with what moved. Nothing else moves the lock, so without this the whole of CI goes on testing whichever day’s resolution was last written
ci-floors	Resolves each declared minimum version and exercises what it resolves, so a floor that has become untrue is found rather than assumed
ci-linkcheck	Checks the external links in README.md, the changelog fragments and the documentation and package sources — excluding the frozen implementation plans and the handful of URLs .lycheeignore records as unreachable by construction — and separately that the University of Wyoming archive still answers tephpy.io, the one external URL this project calls rather than links, which no link checker can judge
ci-topics	Reports monthly on which glossary topics the documentation covers
ci-stale	Marks a long-quiet issue or pull request stale
codeql	The same analysis, weekly, against code that has not changed

On an Issue or a First Pull Request

ci-first-contribution greets somebody’s first issue or pull request and labels it.

When One of Them Finds Something

Four cases are worth knowing in advance, because you meet them without having caused them, or because the remedy is not guessable.

A lock refresh turns the bot’s pull request red on image comparison. When ci-locks moves matplotlib or freetype, rendered figures shift by more than the comparison tolerance. The remedy is to regenerate the baselines on that branch with pixi run baselines, then re-verify across all three test environments (Testing). This is expected rather than a defect in the proposal.

A scheduled job opens an issue. ci-floors, ci-linkcheck and ci-topics each keep a single standing issue and edit it in place rather than filing a new one per run, so the history stays in one place. An issue appearing under your name in a notification is one of these, not something you broke.

Something of yours was labelled stale. ci-stale marks an issue or pull request quiet for six months and closes it four weeks later. Any comment takes the label straight back off. It never touches anything held deliberately — a blocked or paused item, a tracked design question, or the standing reports above.

The browser demo will not start. pixi run docs-all needs a Chromium that pixi does not install. The check names the command to run; Contributing to tephpy carries both forms.

Where the Detail Lives

The workflow files under .github/workflows/ are the authority on what runs. The design specifications carry why each gate is shaped as it is — floors spec §… for the dependency floors, topics spec §… for the coverage report, docs spec §… for the documentation gates.