Repository navigation
Description
Summary
Add contributor-facing guidance on when to use a composite action vs a reusable workflow, so new CI lands at the right altitude across the lecture repos — prompted by a discussion about automated testing of the lecture anaconda environment.
Nothing covers this today: no reusable workflow exists here (workflow_call appears in no file), and neither docs/, CONTRIBUTING.md nor README.md mentions the choice. PLAN.md:81 (backlog item 11) tracks it; CONTRIBUTING.md:98 ("Action Development Guidelines") is the cheapest home — a section there, not a new file, per the docs-trim direction in PLAN.md:80.
Comparison
- Unit of reuse — a sequence of steps called at step level (
steps: - uses:) vs a whole job (or jobs) called at job level (jobs.x.uses:). - Runtime — the caller's job/runner, sharing its filesystem & env, vs its own job on its own runner.
- Job-level config — a composite inherits the caller's
runs-onand owns nostrategy.matrix/services/permissions/environment, taking secrets as plain inputs; a workflow owns all of those, has first-classsecrets:(inherit), and the caller can matrix over it. - Shape — a composite slots freely between your steps, can call other actions, and many independently versioned ones live per repo in subfolders (a monorepo of actions); a workflow is all-or-nothing (no step mid-job), one per file under
.github/workflows/, nesting up to 4 levels.
Default rule: composite action for a reusable piece of a job — a step sequence the caller composes with its own steps (setup-environment, build-lectures); reusable workflow for a reusable whole job/pipeline each repo calls in a few lines via workflow_call. Layer them: workflow for the job shape + matrix/secrets/schedule, composite(s) for the steps it runs.
Worked example — environment test harness
The motivating harness is already built, so it's an example, not a deliverable: .github/workflows/test-actions.yml:432 and :462 run the cold→warm conda-cache chain plus a build-lectures on the restored env on every relevant PR — the first automated tests of the action logic, shipped in v0.10.0 (#114), and why backlog item 9 is struck done at PLAN.md:79. The canary repo QuantEcon/test-actions-lecture-intro exercises the real @v0 chain weekly.
Layering point: the composite (setup-environment) is the unit under test and gives parity with production builds; the rest is inexpressible in a composite — runs-on, the needs: chain handing the cold run's saved cache to the warm run, the relevance gate that lets a skipped job still report success to a required check (:75), and the canary's weekly schedule:.
Unbuilt from the sketch: the python/CUDA matrix and upstream-breakage schedule — test-actions.yml has neither a matrix nor a cron. That belongs as a scheduled matrix on the existing canary, so it goes with #100's coverage gaps rather than staying open here. (#135 covers gating a release on a green canary.)
A python-version matrix over setup-environment would not test two pythons: it only seeds setup-miniconda (setup-environment/action.yml:119) and salts the cache key (:134); the env comes from conda env update -n <environment-name> -f <environment> --prune (:145), so the environment file's python pin wins — fixture .github/fixtures/mini-lectures/environment.yml:5 is python=3.13, and the lecture repos pin the same way. A real env matrix must generate the environment file per leg.
Next steps
- Add the comparison + decision rule to
CONTRIBUTING.mdalongside "Action Development Guidelines" (CONTRIBUTING.md:98), so new CI building blocks pick their layer from it. -
Add a— superseded by the action harness in v0.10.0 (ci: add action-level PR harness for cache and environment actions #114) plus the live canary; residual matrix/schedule work belongs on testing: publish/preview/cache action logic has no automated tests #100.test-environment.ymlreusable workflow and ascripts/test-env.pyreference test as the first example of the "reusable workflow that calls a composite action" pattern.
Context: the consuming side — the manual documenting quantecon/actions as the target deploy architecture — is QuantEcon/QuantEcon.manual#88.
🤖 Issue drafted with Claude Code
Activity