Skip to content

feat(pipeline): batch selettivo centralizzato — auto-detect del target run-batch - #40

Merged
Gabrymi93 merged 2 commits into
mainfrom
ci/batch-centralizzato
Oct 28, 2026
Merged

Gabrymi93 merged 2 commits into
mainfrom
ci/batch-centralizzato

Conversation

@Gabrymi93

@Gabrymi93 Gabrymi93 commented Oct 28, 2026 •

Copy link
Copy Markdown
Member

Sintesi

Centralizza il batch selettivo post-merge: i repo non devono più dichiarare run-batch-command nel YAML — basta un target run-batch nel Makefile.

Contesto collegato

Emerso lavorando su dichiarazioni-italia (#29): con 15 dataset il run completo a ogni merge durava ~7 minuti per pubblicare spesso un dataset solo. Attivando il batch lì, è emerso che il problema è org-wide: 257 dataset su 389 stanno in repo dove il run è sempre completo.

Cosa cambia

  • Bug fix
  • Nuova funzionalità del motore
  • Nuovo plugin sorgente
  • Modifica contratto pubblico (dataset.yml, path output, schema parquet)
  • Refactor / performance
  • Documentazione
  • Dipendenze o CI

Ordine di risoluzione del comando (il primo che esiste vince):

# condizione comando nota
1 run-batch-command impostato quello invariato, retrocompatibile
2 Makefile con target run-batch make run-batch nuovo: la convenzione
3 run-command contiene batch.txt run-command pattern di eurostat, già funzionante
4 nessuna delle precedenti run-command (full) + warning con le istruzioni

Documentazione aggiornata nell'header del workflow e nella descrizione dell'input.

Perché l'auto-detect e non un default generico

Un default tipo toolkit run --batch batch.txt avrebbe rotto i 3 repo con detect-paths ma senza batch, perché hanno pre-step repo-specifici che un comando generico salta:

repo pre-step necessario
giustizia-statistiche TOOLKIT_ALLOW_SCRIPT_SOURCE=1 (6 dataset con source script)
filiere-agroalimentari make seeds (config di support) + script source
open-ccnl make seeds + script source

L'auto-detect usa il comando del repo, che i pre-step li ha già dentro. Dove non esiste, resta il run completo con un warning che dice cosa aggiungere.

Impatto su contratti pubblici

  • Struttura dataset.yml (nuovo campo, cambio obbligatorietà)
  • Path output (nuovo layer, cambio percorso artifact)
  • Schema parquet (nuova colonna, rename, cambio tipo)
  • CLI o MCP tool (nuovo comando, cambio parametro)
  • API pubblica del toolkit (firma funzione, classe, eccezione)

Nessuno: è un input del workflow riusabile, additivo e retrocompatibile. Chi oggi imposta run-batch-command continua a funzionare identico (caso 1).

Verifica

Logica simulata su 6 scenari:

scenario esito
run-batch-command esplicito (open-politica, open-inps, …) Batch mode: make run-batch — invariato
target run-batch nel Makefile, YAML senza run-batch-command Batch mode: make run-batch ← nuovo
run-command: "toolkit run --batch batch.txt" (eurostat) Batch mode: toolkit run --batch batch.txt — invariato
detect-paths senza batch (giustizia-statistiche, filiere-agroalimentari, open-ccnl) Full mode + warning — nessuna rottura
schedule/dispatch Full mode (batch.txt = tutti i dataset)
PR ma batch.txt vuoto Full mode

Nessun cambio di comportamento non voluto: l'auto-detect scatta solo se il Makefile definisce run-batch. Verificato su tutti i repo dell'org che usano questo workflow: nessuno ha un target run-batch non dichiarato nel YAML (dcl-bologna ne ha uno ma usa una pipeline custom, non questa).

  • pytest -m core passa — n/a (nessun test nel repo .github)
  • ruff check . passa — n/a
  • mypy toolkit/ passa — n/a
  • Modificato o aggiunto test — n/a

Checklist PR

  • Perimetro stretto: una modifica al workflow riusabile
  • Se nuovo plugin: n/a
  • Issue collegata o motivazione dell'assenza: emerso dal lavoro su dichiarazioni-italia#29
  • Rimozione di moduli pubblici: n/a

Note per chi revisiona

Rischio residuo: l'auto-detect aggiunge un grep sul Makefile. Se un repo definisse un run-batch con semantica diversa da quella attesa, verrebbe usato. Oggi non succede (verificato), e il log dice sempre quale comando è stato scelto ([run-batch-command] / [target run-batch nel Makefile] / [run-command consuma batch.txt]).

Rollout: dopo il merge, i 3 repo che oggi sprecano il detect continueranno a funzionare come prima (full + warning). Per attivare il batch basta aggiungere un target run-batch al loro Makefile — 3 righe, senza toccare il YAML. Posso farlo in PR separate se volete.

Fix dalla review (commit 9a0e122)

finding azione
Info — grep -q 'batch.txt' <<< "$RUN_COMMAND" è un bashism sostituito con printf '%s' "$RUN_COMMAND" | grep -q 'batch.txt': POSIX, stesso comportamento, a prova di un futuro override di shell: o di un runner diverso. Rieseguiti i 6 scenari: esiti invariati.
Info — grep -qE '^run-batch:' Makefile è la convenzione stretta (file Makefile, target a colonna 0) nessuna azione: è la convenzione dichiarata. Se un repo usasse un altro nome, resta il full + warning (nessun rischio).
Info — il warning comparirà a ogni run sui 3 repo con detect-paths senza batch atteso: è la nudge. Sparisce quando aggiungono il target (3 righe di Makefile, PR separate).
Info — rischio residuo: un run-batch con semantica diversa verrebbe usato dichiarato; il log riporta sempre comando e motivazione ([run-batch-command] / [target run-batch nel Makefile] / [run-command consuma batch.txt]) → diagnosticabile.

…t run-batch

Centralizza il batch selettivo post-merge: i repo non devono più dichiarare
`run-batch-command` nel YAML, basta un target `run-batch` nel Makefile.

**Prima**: il batch funzionava solo se il repo impostava esplicitamente
`run-batch-command`. 3 repo con `detect-paths` costruivano `batch.txt` e poi lo
ignoravano (run completo a ogni merge); ~21 repo non facevano nemmeno il detect.

**Ordine di risoluzione** (il primo che esiste vince):
1. `run-batch-command` esplicito — comportamento invariato, retrocompatibile
2. `make run-batch` se il Makefile del repo definisce il target — **nuova
   convenzione**: il target può includere i pre-step del repo (seeds,
   codelists, env) che un comando generico salterebbe
3. `run-command` se consuma già `batch.txt` (pattern di `eurostat`)
4. `run-command` (run completo) + **warning** che spiega come attivare il batch

**Perché l'auto-detect e non un default generico.** Un default tipo
`toolkit run --batch batch.txt` avrebbe rotto i 3 repo con pre-step:
`giustizia-statistiche` ha bisogno di `TOOLKIT_ALLOW_SCRIPT_SOURCE=1` (6 dataset
con source script), `filiere-agroalimentari` e `open-ccnl` di `make seeds`
(config di support). L'auto-detect usa il comando del repo, che i pre-step li ha
già dentro; dove non esiste resta il run completo con un warning.

**Nessun cambio di comportamento non voluto**: l'auto-detect scatta solo se il
Makefile definisce `run-batch`. Verificato su tutti i repo dell'org che usano il
workflow riusabile: nessuno ha un target `run-batch` non dichiarato nel YAML
(`dcl-bologna` ne ha uno ma usa una pipeline custom, non questo workflow).

Logica verificata su 6 scenari (comando esplicito, auto-detect, run-command che
consuma batch.txt, detect senza batch → warning, schedule → full, batch vuoto → full).
Finding Info della review di #40: `grep -q 'batch.txt' <<< "$RUN_COMMAND"` è un
bashism che funziona solo perché il workflow non dichiara `shell:` (default bash).
Sostituito con `printf '%s' "$RUN_COMMAND" | grep -q 'batch.txt'`: stesso
comportamento, a prova di un futuro override di `shell:` o di un runner diverso.

Rieseguiti i 6 scenari di risoluzione: esiti invariati.
@Gabrymi93
Gabrymi93 merged commit 94c0346 into main Oct 28, 2026
2 checks passed
@Gabrymi93
Gabrymi93 deleted the ci/batch-centralizzato branch October 28, 2026 23:17
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant