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

Aperta Adatta ai principianti
  • Qualcosa non va?
#29 0 commenti 0 reazioni 0 assegnatari Vedi su GitHub

I maintainer di solito rispondono entro 1 giorno

Nessuno ha ancora preso questa issue.

Valutazione

Difficoltà
1/5
Tempo stimato
1-3 ore
Idoneità per principianti
85/100
Tipo di issue
Documentazione
Chiarezza
Specificata chiaramente
Stato di attività
Tranquilla
Stack tecnologico
github-actions
Ambito
ci-cd, documentation

Direzione di ricerca

Inizia dalla sezione «Action Development Guidelines» in CONTRIBUTING.md:98 e dall'indicazione docs-trim intorno a PLAN.md:80-81. Aggiungi una guida rivolta ai contributor che confronti composite actions e reusable workflows e includa una regola decisionale chiara, senza creare un nuovo file. Il lavoro è completo quando la sezione spiega quando è appropriato ciascun livello e riflette l'harness esistente come contesto anziché come un nuovo Deliverable.

Scritto dal modello di indicizzazione a partire dal testo della issue.

Descrizione

documentation

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

Lingua principale
Shell
Stelle
0
Fork
1
Merge medio
20h 3m
PR unite (30g)
48

Preparare l'ambiente

Come iniziare

  1. Leggi tutta la issue e poi la guida ai contributi del progetto.
  2. Commenta sulla issue per dire che te ne occupi tu — evita che due persone facciano lo stesso lavoro.
  3. Fai un fork del repository e lavora su un branch.
  4. Apri una pull request che faccia riferimento al numero della issue.

Altre issue di QuantEcon/actions

Tutte le issue di QuantEcon/actions

Issue simili

Altre issue su Shell/Bash

Ricevi le nuove issue nella tua casella

Un breve riepilogo di issue GitHub adatte ai principianti.