Docs: guidance on composite actions vs reusable workflows (+ env-test harness proposal)

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-on and owns no strategy.matrix/services/permissions/environment, taking secrets as plain inputs; a workflow owns all of those, has first-class secrets: (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.md alongside "Action Development Guidelines" (CONTRIBUTING.md:98), so new CI building blocks pick their layer from it.
• Add a test-environment.yml reusable workflow and a scripts/test-env.py reference test as the first example of the "reusable workflow that calls a composite action" pattern. — superseded by the action harness in v0.10.0 (#114) plus the live canary; residual matrix/schedule work belongs on #100.

Context: the consuming side — the manual documenting quantecon/actions as the target deploy architecture — is QuantEcon/QuantEcon.manual#88.

🤖 Issue drafted with Claude Code

Start with the “Action Development Guidelines” section at CONTRIBUTING.md:98 and the docs-trim direction around PLAN.md:80-81. Add contributor-facing guidance comparing composite actions with reusable workflows and a clear decision rule, without creating a new file. Done means the section explains when each layer is appropriate and reflects the existing harness as context rather than a new deliverable.