Pubblicare Toolkit v1.0 come runtime tecnico dei repo dataset DataCivicLab

[Gabrymi93]

Contesto

Il toolkit è stato progressivamente rafforzato e rifocalizzato come runtime tecnico dei repo dataset DataCivicLab.

Nel modello organizzativo aggiornato:

• .github ospita policy condivise, community health, onboarding GitHub e template issue/PR
• dataciviclab è l’hub pubblico, umano e minimale dell’ecosistema
• toolkit è il runtime tecnico e la fonte della documentazione tecnica di config/path/output
• project-template è il template operativo da cui nascono i repo dataset
• i repo dataset sono i progetti concreti

Questa issue serve a tracciare la pubblicazione del toolkit come componente stabile v1.

Ambito della v1

Il workflow canonico è ora esplicitamente centrato su:

• 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

Questo è il contratto che i repo dataset e i notebook locali sono chiamati a usare.

Cosa è già pronto

Contratto runtime

• i path relativi in dataset.yml sono risolti rispetto alla directory che contiene dataset.yml, non rispetto al cwd
• questo comportamento è coperto nei principali flussi CLI
• output e run record sono stabili e leggibili dai notebook

Config e governance

• config tipizzato con strict mode
• schema config documentato
• compatibilità legacy mantenuta, ma non più promossa nel percorso base

Ergonomia runtime

• aggiunto inspect paths --json per notebook e repo dataset
• resume, profile raw, run raw|clean|mart restano disponibili come tooling avanzato
• gen-sql resta come helper di bootstrap congelato

Documentazione

• README.md rifocalizzato sul workflow canonico
• docs/advanced-workflows.md
• docs/feature-stability.md
• docs/notebook-contract.md

CI / qualità

• CI matrix Ubuntu/Windows, Python 3.10/3.11
• coverage in CI
• smoke install/CLI
• build + twine check

Obiettivo

Pubblicare toolkit v1 come motore tecnico stabile dei repo dataset nell’ecosistema DataCivicLab.

Criteri di accettazione

• la repo si presenta chiaramente come runtime tecnico, non come hub organizzativo
• il workflow canonico è documentato ed è coerente
• i contratti di path/config/output sono stabili e testati
• i repo dataset possono usare inspect paths --json senza ricostruire i path a mano
• le feature avanzate restano supportate ma non sono più presentate come percorso base
• la repo è pronta per essere collegata dal project-template e dall’hub pubblico dell’organizzazione

Follow-up opzionali

• rafforzare i riferimenti dal project-template ai docs del toolkit
• continuare a ridurre la superficie pubblica non essenziale nel README
• valutare deprecazioni future solo dopo evidenza d’uso reale

Note

Questa issue riguarda la pubblicazione del toolkit come componente tecnico stabile dell’ecosistema.

Non riguarda:

• governance generale dell’organizzazione
• policy condivise GitHub
• logica dataset-specifica