v1.1.0

1.1.0

Questa release consolida il toolkit come runtime tecnico dei repo dataset DataCivicLab, riducendo il surface area non core e chiarendo meglio i contract di runtime, output e notebook.

Il workflow canonico resta:

• toolkit run all --config dataset.yml
• toolkit validate all --config dataset.yml
• toolkit status --dataset <dataset> --year <year> --latest --config dataset.yml
• toolkit inspect paths --config dataset.yml --year <year> --json

Cambiamenti principali

Riduzione del surface area

• rimossi shim deprecated di core
• rimosso gen-sql
• rimossi plugin periferici/experimental
• chiariti meglio i confini tra:
  • runtime core
  • tooling avanzato
  • compatibilità legacy

Miglioramenti al motore

• refactor del flusso di lettura DuckDB in CLEAN
• refactor della selezione input CLEAN
• refactor dell’orchestrazione e validazione CLEAN
• refactor del profiling RAW
• aggiunti hint minimi nel metadata RAW per facilitare lettura e diagnostica

Chiarezza del contract runtime/output

• distinzione esplicita tra:
  • metadata.json
  • manifest.json
  • run record in data/_runs/...
  • inspect paths --json
• separato nel codice il concetto di:
  • manifest standard di layer
  • manifest RAW libero/layer-specific

Test e manutenzione

• suite test stratificata con marker:
  • core
  • advanced
  • compat
• branch finale verificato con:
  • 146 passed
  • ruff check pulito

Documentazione

• README riallineato al workflow canonico
• chiariti i confini del toolkit nell’ecosistema DataCivicLab
• aggiornate le docs su:
  • workflow avanzati
  • feature stability
  • notebook contract
  • runtime boundaries
  • smoke e profiling docs

Impatto

Questa release rende il toolkit:

• più piccolo
• più leggibile
• più coerente con project-template
• più chiaro per notebook e repo dataset
• più facile da mantenere come motore tecnico condiviso

Note

Le feature advanced restano supportate ma non fanno parte del percorso base da promuovere nei nuovi repo dataset:

• resume
• profile raw
• run raw|clean|mart
• artifact policy avanzata
• compatibilità legacy

v1.0.0

1.0.0

Questa release pubblica il toolkit come runtime tecnico stabile dei repo dataset DataCivicLab.

Il toolkit viene definito come motore comune della pipeline dati nell’ecosistema, con un workflow canonico chiaro:

• toolkit run all --config dataset.yml
• toolkit validate all --config dataset.yml
• toolkit status --dataset <dataset> --year <year> --latest --config dataset.yml
• toolkit inspect paths --config dataset.yml --year <year> --json

Cosa include questa release

Runtime stabile

• pipeline RAW -> CLEAN -> MART
• validazione esplicita dei layer
• run tracking persistente
• contract stabile per config, path relativi e output runtime
• helper inspect paths --json per notebook e repo dataset

Hardening del motore

• config tipizzato con strict mode
• supporto esplicito alle deprecazioni config con warning/error coerenti
• miglioramento della robustezza cross-platform
• chiusura esplicita delle connessioni DuckDB
• resume più robusto con verifica degli artefatti minimi

Test e CI

• suite test estesa su config, path contract, CLI, validation e workflow end-to-end
• smoke test install/CLI
• smoke end-to-end piccoli e deterministici
• CI matrix su Ubuntu/Windows e Python 3.10/3.11
• coverage in CI
• build e twine check verificati

Documentazione

• schema config documentato
• esempi YAML minimi e completi
• README riallineato al workflow reale
• docs dedicate per:
  • workflow avanzati
  • stabilità feature
  • notebook contract
  • runtime boundaries

Contratto stabile per i repo dataset

Il toolkit è pensato come motore tecnico dell’ecosistema:

• .github gestisce policy condivise e community health
• dataciviclab è l’hub pubblico dell’organizzazione
• toolkit è il runtime tecnico
• project-template è il template operativo dei repo dataset
• i repo dataset contengono i progetti concreti

I repo dataset e i notebook locali dovrebbero leggere gli output reali del toolkit senza ricostruire a mano i path di runtime.

Verifica finale

• CI verde su Ubuntu/Windows, Python 3.10/3.11
• build python -m build verificata
• twine check dist/* verificato
• coverage sopra soglia minima
• workflow canonico coperto da test e smoke

Note

Questa release stabilisce il toolkit come componente tecnico comune del Lab.

Le feature avanzate restano supportate, ma non fanno parte del percorso base da promuovere nei nuovi repo dataset:

• resume
• profile raw
• run raw|clean|mart
• artifact policy avanzata
• compatibilità legacy