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

Abierto Apto para principiantes
  • ¿Algo no está bien?
#29 0 comentarios 0 reacciones 0 asignados Ver en GitHub

Los mantenedores suelen responder en 1 día

Nadie ha tomado este issue todavía.

Evaluación

Dificultad
1/5
Tiempo estimado
1-3 horas
Aptitud para principiantes
85/100
Tipo de issue
Documentación
Claridad
Bien especificado
Estado de actividad
Tranquilo
Stack tecnológico
github-actions
Área
ci-cd, documentation

Línea de trabajo

Comienza con la sección «Action Development Guidelines» en CONTRIBUTING.md:98 y con la dirección de docs-trim alrededor de PLAN.md:80-81. Añade orientación dirigida a los colaboradores que compare composite actions con reusable workflows y una regla de decisión clara, sin crear un archivo nuevo. Se considera terminado cuando la sección explica cuándo es apropiada cada capa y refleja el harness existente como contexto, no como un nuevo Deliverable.

Escrito por el modelo de indexación a partir del texto del issue.

Descripción

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

Lenguaje dominante
Shell
Estrellas
0
Forks
1
Merge medio
20 h 3 min
PR fusionados (30 d)
48

Preparar el entorno

Primeros pasos

  1. Lee el issue completo y luego la guía de contribución del proyecto.
  2. Comenta en el issue que vas a ocuparte — evita que dos personas hagan lo mismo.
  3. Haz un fork del repositorio y trabaja en una rama.
  4. Abre un pull request que haga referencia al número del issue.

Más de QuantEcon/actions

Todos los issues de QuantEcon/actions

Issues similares

Más issues de Shell/Bash

Recibe los nuevos issues en tu correo

Un resumen breve de issues de GitHub para principiantes.