diff --git a/.editorconfig b/.editorconfig new file mode 100644 index 0000000..2d8e5b5 --- /dev/null +++ b/.editorconfig @@ -0,0 +1,18 @@ +root = true + +[*] +charset = utf-8 +end_of_line = lf +insert_final_newline = true +indent_style = space +indent_size = 2 +trim_trailing_whitespace = true + +[*.py] +indent_size = 4 + +[*.md] +trim_trailing_whitespace = false + +[Makefile] +indent_style = tab diff --git a/.gitattributes b/.gitattributes new file mode 100644 index 0000000..8fd7d12 --- /dev/null +++ b/.gitattributes @@ -0,0 +1,9 @@ +* text=auto eol=lf + +*.md text eol=lf +*.yml text eol=lf +*.yaml text eol=lf +*.json text eol=lf +*.txt text eol=lf +*.sql text eol=lf +*.py text eol=lf diff --git a/.github/seed-issues/00_kickoff.md b/.github/seed-issues/00_kickoff.md index 5671614..88e22ab 100644 --- a/.github/seed-issues/00_kickoff.md +++ b/.github/seed-issues/00_kickoff.md @@ -1,48 +1,29 @@ --- -title: "[Kickoff] Definire domanda civica, perimetro e contratto iniziale del dataset" +title: "[Kickoff] Definire perimetro, domanda e contratto iniziale" labels: ["LEAD", "METODO"] assignees: [] --- -## Perche questa fase conta - -Qui si decide se il progetto ha una domanda utile, comprensibile e davvero sostenibile nel tempo. -Un kickoff fatto bene evita di costruire dati che poi non rispondono alla domanda iniziale. - -## Output visibile al pubblico - -Una spiegazione chiara di cosa vuole capire il progetto e di quali dati usera. - ## Obiettivo -Avviare il progetto dataset con perimetro chiaro, domanda civica misurabile e contratto toolkit-first coerente con il template. +Aprire il progetto con un perimetro chiaro e un contratto minimo coerente con il template. + +Usare questa issue solo se il repo e appena nato o se il perimetro e ancora ambiguo. ## Checklist -- [ ] Definire una sola domanda civica, chiara e misurabile +- [ ] Definire una domanda guida chiara - [ ] Compilare `dataset.yml` con `dataset.name`, `dataset.years` e `root` -- [ ] Verificare che i path in config siano root-relative POSIX - [ ] Confermare la struttura canonica `sql/clean.sql` e `sql/mart/.sql` -- [ ] Allineare ruoli e ownership con `docs/lab_links.md` +- [ ] Verificare che i path in config siano root-relative POSIX - [ ] Verificare che `tests/test_contract.py` sia verde in locale -## Output atteso - -Progetto inizializzato con contratto di base valido e documentazione minima pronta per il source onboarding. - -## Supporto operativo - -- notebook consigliato: `notebooks/00_quickstart.ipynb` -- comando minimo: `py -m pytest tests/test_contract.py` - ## File da toccare - `dataset.yml` - `README.md` -- `docs/lab_links.md` ## Acceptance criteria -- `dataset.yml` esiste in root ed e coerente con il contratto smoke reale -- il perimetro del progetto e documentato in modo comprensibile -- `pytest tests/test_contract.py` passa -- il progetto puo passare alla fase Source onboarding senza ambiguita su nome dataset, anni e scope +- `dataset.yml` esiste ed e coerente con il contratto del template +- il perimetro del progetto e leggibile nel `README` +- `py -m pytest tests/test_contract.py` passa diff --git a/.github/seed-issues/01_civic_questions.md b/.github/seed-issues/01_civic_questions.md deleted file mode 100644 index 3a0aeaf..0000000 --- a/.github/seed-issues/01_civic_questions.md +++ /dev/null @@ -1,47 +0,0 @@ ---- -title: "[Questions] Esplicitare domande civiche, metriche e ipotesi iniziali" -labels: ["METODO", "LEAD"] -assignees: [] ---- -## Perche questa fase conta - -Un progetto dati utile nasce da domande chiare, non da una pipeline costruita nel vuoto. -Questa fase serve a collegare il lavoro tecnico a un problema pubblico leggibile. - -## Output visibile al pubblico - -Un set di domande guida che spiega cosa il progetto prova a capire e con quali misure. - -## Obiettivo - -Definire le domande civiche che guideranno fonti, metriche, unità di analisi e output del progetto. - -## Checklist - -- [ ] 3-5 domande civiche esplicite -- [ ] 3-5 metriche collegate -- [ ] Ipotesi dichiarate -- [ ] Coerenza con unità di analisi - -## Output atteso - -Una base pubblica e metodologica chiara da cui far discendere le scelte su fonti, CLEAN, MART e output finali. - -## Supporto operativo - -- notebook consigliato: nessuno, il lavoro e principalmente metodologico e documentale -- file guida: `README.md`, `docs/overview.md`, `docs/decisions.md` - -## File da toccare - -- `README.md` -- `docs/overview.md` -- `docs/lab_links.md` -- `docs/decisions.md` - -## Acceptance criteria - -- le domande guida sono scritte in linguaggio semplice -- le metriche proposte sono coerenti con le domande -- le ipotesi iniziali sono esplicitate -- c'e coerenza fra domande, metriche e unità di analisi diff --git a/.github/seed-issues/01_sources.md b/.github/seed-issues/01_sources.md new file mode 100644 index 0000000..8a06308 --- /dev/null +++ b/.github/seed-issues/01_sources.md @@ -0,0 +1,32 @@ +--- +title: "[Sources] Verificare fonte, licenza e configurazione di ingestione" +labels: ["DATA", "METODO"] +assignees: [] +--- +## Obiettivo + +Qualificare una fonte e codificare in modo riproducibile come il toolkit deve leggerla. + +Usare questa issue quando il blocco vero e ancora sulla fonte, non su CLEAN o MART. + +## Checklist + +- [ ] Identificare fonte primaria, URL canonico e frequenza di aggiornamento +- [ ] Aggiornare `raw.sources[].type` e `raw.sources[].args` in `dataset.yml` +- [ ] Documentare licenza, coverage e refresh in `docs/sources.md` +- [ ] Registrare trade-off rilevanti in `docs/decisions.md` +- [ ] Verificare che non esistano path assoluti o riferimenti locali +- [ ] Rieseguire `py -m pytest tests/test_contract.py` + +## File da toccare + +- `dataset.yml` +- `docs/sources.md` +- `docs/decisions.md` + +## Acceptance criteria + +- la fonte e verificabile e documentata +- `raw.sources` e compilato con campi sufficienti all'esecuzione +- `docs/sources.md` contiene note minime su licenza, refresh e limiti noti +- `py -m pytest tests/test_contract.py` passa diff --git a/.github/seed-issues/02_raw.md b/.github/seed-issues/02_raw.md new file mode 100644 index 0000000..d0d56e9 --- /dev/null +++ b/.github/seed-issues/02_raw.md @@ -0,0 +1,32 @@ +--- +title: "[RAW] Rendere l'ingestione riproducibile e tracciabile" +labels: ["DATA"] +assignees: [] +--- +## Obiettivo + +Ottenere un layer RAW eseguibile e ripetibile, senza committare output in repo. + +Usare questa issue quando la fonte e gia stata scelta ma il run RAW non e ancora affidabile. + +## Checklist + +- [ ] Verificare `raw.sources[]`, `primary` ed eventuale extractor in `dataset.yml` +- [ ] Eseguire `toolkit run raw --config dataset.yml` +- [ ] Usare `toolkit inspect paths --config dataset.yml --year --json` per localizzare gli artifact RAW +- [ ] Controllare `manifest.json`, `metadata.json` e `raw_validation.json` +- [ ] Confermare che `data/` non contenga output committati +- [ ] Documentare eventuali eccezioni o failure modes in `docs/decisions.md` + +## File da toccare + +- `dataset.yml` +- `docs/decisions.md` +- `docs/sources.md` + +## Acceptance criteria + +- il run RAW completa o il blocco e documentato in modo riproducibile +- nessun output RAW viene aggiunto sotto `data/` +- gli artifact minimi del RAW sono attesi sotto `root/data/raw///` +- l'input per CLEAN e deterministico diff --git a/.github/seed-issues/02_sources.md b/.github/seed-issues/02_sources.md deleted file mode 100644 index 725c0e0..0000000 --- a/.github/seed-issues/02_sources.md +++ /dev/null @@ -1,49 +0,0 @@ ---- -title: "[Sources] Onboarding fonti, licenza, refresh e decisioni di ingestione" -labels: ["DATA", "METODO"] -assignees: [] ---- -## Perche questa fase conta - -Se la fonte non e chiara, tutto il resto del progetto diventa fragile. -Questa fase serve a capire da dove arrivano i dati e con quali limiti. - -## Output visibile al pubblico - -Una scheda semplice delle fonti usate, con link e note di contesto. - -## Obiettivo - -Qualificare la fonte e codificare in modo riproducibile come il toolkit deve leggerla. - -## Checklist - -- [ ] Identificare fonte primaria, URL canonico e frequenza di aggiornamento -- [ ] Aggiornare `raw.sources[].type` e `raw.sources[].args` in `dataset.yml` -- [ ] Documentare licenza, coverage, refresh cadence e note in `docs/sources.md` -- [ ] Registrare trade-off e assunzioni di ingestione in `docs/decisions.md` -- [ ] Verificare che non esistano path assoluti o riferimenti locali -- [ ] Rieseguire i contract tests - -## Output atteso - -Fonte verificata e configurata in `dataset.yml`, con documentazione sufficiente per procedere al layer RAW. - -## Supporto operativo - -- notebook consigliato: `notebooks/01_inspect_raw.ipynb` -- comando minimo: `toolkit run raw --config dataset.yml` -- dopo il run usa: `toolkit inspect paths --config dataset.yml --year --json` - -## File da toccare - -- `dataset.yml` -- `docs/sources.md` -- `docs/decisions.md` - -## Acceptance criteria - -- la fonte e verificabile e documentata -- `raw.sources` e compilato con campi sufficienti all'esecuzione -- `docs/sources.md` contiene note su licenza, refresh e limiti noti -- `pytest tests/test_contract.py` passa diff --git a/.github/seed-issues/04_clean.md b/.github/seed-issues/03_clean.md similarity index 59% rename from .github/seed-issues/04_clean.md rename to .github/seed-issues/03_clean.md index fc40d99..bbb26e2 100644 --- a/.github/seed-issues/04_clean.md +++ b/.github/seed-issues/03_clean.md @@ -1,21 +1,14 @@ --- -title: "[CLEAN] Implementare normalizzazione, required columns e validazioni CLEAN" +title: "[CLEAN] Normalizzare input e chiudere il contratto CLEAN minimo" labels: ["DATA"] assignees: [] --- -## Perche questa fase conta - -Qui il dato diventa davvero leggibile e confrontabile. -Una buona fase CLEAN riduce errori, ambiguita e lavoro manuale futuro. - -## Output visibile al pubblico - -Un dataset piu chiaro, con colonne coerenti e significato documentato. - ## Obiettivo Portare il dataset da RAW a CLEAN con SQL esplicita, schema documentato e validazioni minime. +Usare questa issue quando il problema vero e sulla lettura, normalizzazione o stabilita dello schema. + ## Checklist - [ ] Implementare o aggiornare `sql/clean.sql` @@ -25,17 +18,7 @@ Portare il dataset da RAW a CLEAN con SQL esplicita, schema documentato e valida - [ ] Eseguire `toolkit validate clean --config dataset.yml` - [ ] Usare `toolkit inspect paths --config dataset.yml --year --json` per localizzare il layer CLEAN - [ ] Aggiornare `docs/data_dictionary.md` per il layer CLEAN -- [ ] Loggare assunzioni e mapping in `docs/decisions.md` - -## Output atteso - -Layer CLEAN riproducibile, con schema e regole di validazione sufficienti per alimentare i mart. - -## Supporto operativo - -- notebook consigliato: `notebooks/02_inspect_clean.ipynb` -- path attesi: `root/data/clean///` -- comando di discovery: `toolkit inspect paths --config dataset.yml --year --json` +- [ ] Loggare mapping o assunzioni non ovvie in `docs/decisions.md` ## File da toccare diff --git a/.github/seed-issues/03_raw.md b/.github/seed-issues/03_raw.md deleted file mode 100644 index 7f62545..0000000 --- a/.github/seed-issues/03_raw.md +++ /dev/null @@ -1,49 +0,0 @@ ---- -title: "[RAW] Rendere riproducibile l'ingestione RAW con il toolkit" -labels: ["DATA"] -assignees: [] ---- -## Perche questa fase conta - -Questa e la base del progetto: se il dato in ingresso non e stabile o tracciabile, anche le analisi finali diventano deboli. - -## Output visibile al pubblico - -Una fonte acquisita in modo ripetibile, con traccia di cosa e stato usato e quando. - -## Obiettivo - -Ottenere un layer RAW eseguibile e ripetibile, senza committare output in repo. - -## Checklist - -- [ ] Verificare `raw.sources[]`, `primary` ed eventuale extractor in `dataset.yml` -- [ ] Eseguire `toolkit run raw --config dataset.yml` -- [ ] Usare `toolkit inspect paths --config dataset.yml --year --json` per localizzare gli artifact RAW -- [ ] Controllare `manifest.json`, `metadata.json` e `raw_validation.json` -- [ ] Controllare metadata, manifest e validation report del RAW -- [ ] Confermare che `data/` non contenga output committati -- [ ] Aggiornare `docs/decisions.md` con eventuali eccezioni o failure modes - -## Output atteso - -RAW eseguibile con report minimi di validazione e metadata disponibili negli artifact di run. - -## Supporto operativo - -- notebook consigliato: `notebooks/01_inspect_raw.ipynb` -- path attesi: `root/data/raw///` -- comando di discovery: `toolkit inspect paths --config dataset.yml --year --json` - -## File da toccare - -- `dataset.yml` -- `docs/decisions.md` -- `docs/sources.md` - -## Acceptance criteria - -- il run RAW completa o il blocco e documentato in modo riproducibile -- nessun output RAW viene aggiunto sotto `data/` -- gli artifact minimi del RAW sono attesi sotto `root/data/raw///` -- il progetto puo passare a CLEAN con input RAW deterministico diff --git a/.github/seed-issues/05_mart.md b/.github/seed-issues/04_mart.md similarity index 60% rename from .github/seed-issues/05_mart.md rename to .github/seed-issues/04_mart.md index ff39aea..cc3fa1a 100644 --- a/.github/seed-issues/05_mart.md +++ b/.github/seed-issues/04_mart.md @@ -1,21 +1,14 @@ --- -title: "[MART] Costruire tabelle analitiche e regole di validazione MART" +title: "[MART] Costruire tabelle finali e validation rules essenziali" labels: ["DATA", "METODO"] assignees: [] --- -## Perche questa fase conta - -Qui il progetto inizia a produrre risposte utilizzabili. -I mart sono la parte che alimenta analisi, dashboard e insight condivisibili. - -## Output visibile al pubblico - -Tabelle finali leggibili, da cui ricavare indicatori e confronti. - ## Obiettivo Produrre uno o piu mart orientati a KPI e output finali, con tabella/e e validation rules esplicite. +Usare questa issue quando CLEAN regge gia e il prossimo blocco e arrivare a un output leggibile. + ## Checklist - [ ] Creare o aggiornare `sql/mart/
.sql` per ogni tabella dichiarata @@ -26,16 +19,6 @@ Produrre uno o piu mart orientati a KPI e output finali, con tabella/e e validat - [ ] Verificare required columns, chiavi, `not_null`, `min_rows` e KPI sanity - [ ] Aggiornare `docs/data_dictionary.md` con granularita, KPI e semantica dei mart -## Output atteso - -Mart pronti per dashboard o report, con SQL separata per tabella e regole di validazione chiare. - -## Supporto operativo - -- notebook consigliato: `notebooks/03_explore_mart.ipynb` -- comando minimo: `toolkit run mart --config dataset.yml` -- comando di discovery: `toolkit inspect paths --config dataset.yml --year --json` - ## File da toccare - `sql/mart/
.sql` @@ -48,4 +31,4 @@ Mart pronti per dashboard o report, con SQL separata per tabella e regole di val - ogni tabella dichiarata in `mart.tables[]` ha un file SQL dedicato - eventuali regole MART dichiarate in `dataset.yml` sono coerenti con le tabelle pubblicate - rowcount sanity e duplicate check sono stati eseguiti -- il progetto puo passare a QA con mart leggibili e validabili +- il progetto produce almeno un mart leggibile e validabile diff --git a/.github/seed-issues/05_release.md b/.github/seed-issues/05_release.md new file mode 100644 index 0000000..37b2424 --- /dev/null +++ b/.github/seed-issues/05_release.md @@ -0,0 +1,33 @@ +--- +title: "[Release] Preparare README, output minimo e handoff" +labels: ["DOCS", "LEAD"] +assignees: [] +--- +## Obiettivo + +Portare il progetto a una release riproducibile, spiegabile e pronta per handoff. + +Usare questa issue solo quando il progetto ha gia un output reale da presentare. + +## Checklist + +- [ ] Aggiornare `README.md` con scopo, metodo, output e limiti +- [ ] Verificare `docs/lab_links.md` per hub DataCivicLab, policy comuni e riferimenti al toolkit +- [ ] Confermare che `output.artifacts` resti su `minimal` o motivare eccezioni +- [ ] Collegare eventuale dashboard o report ai mart corretti +- [ ] Verificare che documentazione e artifact minimi siano coerenti +- [ ] Preparare PR o release notes interne + +## File da toccare + +- `README.md` +- `docs/overview.md` +- `docs/lab_links.md` +- `docs/data_dictionary.md` + +## Acceptance criteria + +- README e docs descrivono chiaramente cosa e stato rilasciato +- il progetto e riprendibile da terzi senza conoscenza implicita +- gli artifact minimi attesi sono coerenti con la policy del template +- i gate precedenti sono chiusi o le eccezioni sono documentate diff --git a/.github/seed-issues/10_maintenance.md b/.github/seed-issues/06_maintenance.md similarity index 55% rename from .github/seed-issues/10_maintenance.md rename to .github/seed-issues/06_maintenance.md index 5fffb28..af87b0e 100644 --- a/.github/seed-issues/10_maintenance.md +++ b/.github/seed-issues/06_maintenance.md @@ -1,21 +1,14 @@ --- -title: "[Maintenance] Gestire nuove annualita, cambi schema e regressioni" +title: "[Maintenance] Gestire nuove annualita, drift schema e regressioni" labels: ["DATA", "MAINTENANCE"] assignees: [] --- -## Perche questa fase conta - -I dataset non restano fermi: cambiano fonti, anni, regole e definizioni. -Questa fase serve a mantenere il progetto utile anche dopo la prima release. - -## Output visibile al pubblico - -Un progetto che resta aggiornabile e non si rompe al primo cambiamento di fonte. - ## Obiettivo Definire il lavoro necessario per mantenere il dataset nel tempo quando cambiano fonte, schema o regole. +Usare questa issue quando il progetto esiste gia e arriva un cambio reale di anno, fonte o schema. + ## Checklist - [ ] Aggiornare `dataset.yml` per nuove annualita o sorgenti @@ -25,15 +18,6 @@ Definire il lavoro necessario per mantenere il dataset nel tempo quando cambiano - [ ] Aggiornare `docs/sources.md`, `docs/data_dictionary.md` e `docs/decisions.md` - [ ] Documentare regressioni o incompatibilita -## Output atteso - -Piano di manutenzione chiaro e procedimento ripetibile per evolvere il dataset senza rompere il contratto del template. - -## Supporto operativo - -- notebook consigliato: `notebooks/01_inspect_raw.ipynb`, `notebooks/02_inspect_clean.ipynb`, `notebooks/03_explore_mart.ipynb` -- comandi minimi: `py -m pytest tests/test_contract.py`, `toolkit run all --config dataset.yml`, `toolkit validate all --config dataset.yml` - ## File da toccare - `dataset.yml` diff --git a/.github/seed-issues/06_validation_qa.md b/.github/seed-issues/06_validation_qa.md deleted file mode 100644 index 50232e1..0000000 --- a/.github/seed-issues/06_validation_qa.md +++ /dev/null @@ -1,49 +0,0 @@ ---- -title: "[QA] Chiudere validazioni, contract tests e smoke opzionale" -labels: ["QA", "DATA"] -assignees: [] ---- -## Perche questa fase conta - -E il momento in cui si verifica se il progetto regge davvero. -Serve a evitare output convincenti ma fragili o poco affidabili. - -## Output visibile al pubblico - -Un dataset piu affidabile, con controlli espliciti e anomalie residue tracciate. - -## Obiettivo - -Chiudere il gate tecnico di qualita con contract tests verdi, validazioni dataset e smoke opzionale documentato. - -## Checklist - -- [ ] Eseguire `py -m pytest tests/test_contract.py` -- [ ] Verificare che la CI `contract` sia verde -- [ ] Verificare che la CI `smoke` sia documentata e attivabile con `RUN_SMOKE=1` -- [ ] Rieseguire `toolkit validate all --config dataset.yml` -- [ ] Controllare outlier, rowcount sanity, duplicates e coerenza dei KPI -- [ ] Aprire issue residue per anomalie non bloccanti - -## Output atteso - -Gate QA superato, con standard minimo del Lab rispettato e stato di qualita esplicito. - -## Supporto operativo - -- notebook consigliato: `notebooks/04_quality_checks.ipynb` -- comando di stato: `toolkit status --dataset --year --latest --config dataset.yml` - -## File da toccare - -- `tests/test_contract.py` -- `.github/workflows/ci.yml` -- `README.md` -- `docs/decisions.md` - -## Acceptance criteria - -- i contract tests passano -- il job `contract` in CI e sempre eseguibile senza dipendere da toolkit su PyPI -- il job `smoke` resta opzionale e documentato -- le anomalie residue sono documentate o trasformate in issue diff --git a/.github/seed-issues/07_dashboard.md b/.github/seed-issues/07_dashboard.md deleted file mode 100644 index f0cd351..0000000 --- a/.github/seed-issues/07_dashboard.md +++ /dev/null @@ -1,46 +0,0 @@ ---- -title: "[Release] Dashboard o output pubblico collegato ai MART" -labels: ["VIZ", "OPTIONAL"] -assignees: [] ---- -## Perche questa fase conta - -E la fase in cui il lavoro diventa leggibile anche fuori dal team tecnico. -Serve a trasformare tabelle finali in un output che aiuti davvero chi legge. - -## Output visibile al pubblico - -Una dashboard, un report o una pagina che spiega cosa emerge dai dati. - -## Obiettivo - -Preparare un output pubblico che consumi i mart prodotti dal progetto. - -## Checklist - -- [ ] Identificare il mart sorgente e i KPI che alimentano l'output -- [ ] Documentare limiti, assunzioni e ultimo aggiornamento in `dashboard/README.md` -- [ ] Verificare coerenza fra dashboard e `docs/data_dictionary.md` -- [ ] Esplicitare cosa emerge e cosa non emerge dall'output -- [ ] Collegare l'output nel `README.md` - -## Output atteso - -Dashboard, report o pagina pubblica leggibile e coerente con i mart del progetto. - -## Supporto operativo - -- notebook consigliato: `notebooks/05_dashboard_export.ipynb` - -## File da toccare - -- `dashboard/README.md` -- `README.md` -- `docs/data_dictionary.md` - -## Acceptance criteria - -- l'output usa solo mart documentati -- KPI e limiti sono spiegati in modo leggibile -- il collegamento con il dataset rilasciato e tracciabile -- l'issue non blocca la release del dataset se l'output pubblico non e previsto diff --git a/.github/seed-issues/08_release.md b/.github/seed-issues/08_release.md deleted file mode 100644 index 2fcf1af..0000000 --- a/.github/seed-issues/08_release.md +++ /dev/null @@ -1,62 +0,0 @@ ---- -title: "[Release] Preparare release del dataset, README e artifacts minimi" -labels: ["DOCS", "LEAD"] -assignees: [] ---- -## Perche questa fase conta - -Questa fase rende il progetto condivisibile anche con chi arriva da fuori. -Una buona release rende chiaro cosa esiste, cosa si puo usare e con quali limiti. - -## Output visibile al pubblico - -Una homepage chiara, una overview leggibile e una release spiegata bene. - -## Obiettivo - -Portare il progetto a una release riproducibile, spiegabile e pronta per handoff. - -## Checklist - -- [ ] Aggiornare `README.md` con scopo, metodo, output e limiti -- [ ] Verificare `docs/lab_links.md` per hub DataCivicLab, policy comuni e riferimenti al toolkit -- [ ] Confermare che `output.artifacts` resti su `minimal` o motivare eccezioni -- [ ] Collegare eventuale dashboard o report ai mart corretti -- [ ] Verificare che documentazione e artifact minimi siano coerenti -- [ ] Preparare PR o release notes interne - -## Public-facing readiness - -- [ ] README pubblico-first ok -- [ ] `docs/overview.md` presente -- [ ] almeno 3 domande o insight presenti nel README -- [ ] `docs/data_dictionary.md` aggiornato almeno al minimo - -## Civic clarity check - -- [ ] Le domande guida sono ancora rilevanti? -- [ ] Le metriche rispondono davvero alle domande? -- [ ] Ci sono insight scritti in linguaggio semplice? - -## Output atteso - -Release interna o pubblica con documentazione finale coerente con i dati e con i mart prodotti. - -## Supporto operativo - -- notebook consigliato: `notebooks/00_quickstart.ipynb` -- comandi minimi: `py -m pytest tests/test_contract.py` e `toolkit validate all --config dataset.yml` - -## File da toccare - -- `README.md` -- `docs/overview.md` -- `docs/lab_links.md` -- `docs/data_dictionary.md` - -## Acceptance criteria - -- README e docs descrivono chiaramente cosa e stato rilasciato -- il progetto e riprendibile da terzi senza conoscenza implicita -- gli artifact minimi attesi sono coerenti con la policy del template -- i gate precedenti sono chiusi o le eccezioni sono documentate diff --git a/.github/seed-issues/09_docs_decisions_dictionary.md b/.github/seed-issues/09_docs_decisions_dictionary.md deleted file mode 100644 index ed4e8b5..0000000 --- a/.github/seed-issues/09_docs_decisions_dictionary.md +++ /dev/null @@ -1,48 +0,0 @@ ---- -title: "[Docs] Aggiornare decision log e data dictionary del progetto" -labels: ["DOCS", "METODO"] -assignees: [] ---- -## Perche questa fase conta - -Un progetto dati e utile solo se altre persone riescono a capirlo e riprenderlo. -Questa fase rende visibili scelte, significato dei campi e limiti. - -## Output visibile al pubblico - -Documentazione leggibile che spiega cosa significano i dati e come interpretarli. - -## Obiettivo - -Tenere allineata la documentazione strutturata del dataset durante tutto il lifecycle del progetto. - -## Checklist - -- [ ] Aggiornare `docs/decisions.md` con decisioni, eccezioni e trade-off -- [ ] Aggiornare `docs/data_dictionary.md` per RAW, CLEAN e MART -- [ ] Verificare coerenza con `docs/sources.md` -- [ ] Verificare coerenza con `docs/lab_links.md` -- [ ] Allineare esempi e naming in README e workflow dataset - -## Output atteso - -Decision log e data dictionary completi, utili per review, handoff e manutenzione futura. - -## Supporto operativo - -- notebook consigliato: `notebooks/02_inspect_clean.ipynb` e `notebooks/03_explore_mart.ipynb` - -## File da toccare - -- `docs/decisions.md` -- `docs/data_dictionary.md` -- `docs/sources.md` -- `docs/lab_links.md` -- `README.md` - -## Acceptance criteria - -- il decision log spiega le scelte non ovvie -- il data dictionary descrive i campi essenziali di CLEAN e MART -- la documentazione e coerente con `dataset.yml` e con la SQL canonica -- il progetto puo passare review metodologica senza knowledge transfer verbale diff --git a/.github/seed-issues/README.md b/.github/seed-issues/README.md new file mode 100644 index 0000000..97ab8bd --- /dev/null +++ b/.github/seed-issues/README.md @@ -0,0 +1,29 @@ +# Seed Issues + +Questa cartella contiene seed issue leggere per repo dataset basate su `project-template`. + +Non vanno usate come pacchetto standard da aprire tutto insieme. +Servono come libreria di partenza da cui derivare 2-4 issue piccole, ancorate a un problema reale del progetto. + +Regole pratiche: + +- aprire solo issue che corrispondono a un blocco o a un prossimo passo reale +- preferire issue piccole e chiudibili in poco tempo +- evitare issue generiche tipo "fare QA completa" o "fare dashboard" se il progetto non e pronto +- adattare sempre titolo, checklist e acceptance criteria al dataset concreto + +Seed consigliate come base: + +- `00_kickoff.md` +- `01_sources.md` +- `02_raw.md` +- `03_clean.md` +- `04_mart.md` +- `05_release.md` +- `06_maintenance.md` + +Le altre fasi del lifecycle restano importanti, ma di solito funzionano meglio: + +- dentro il README o le note metodologiche +- come parte di issue piu piccole +- nel repo hub `dataciviclab` invece che nella repo tecnica del dataset diff --git a/.github/workflows/seed-issues.yml b/.github/workflows/seed-issues.yml index 89ca285..7241e57 100644 --- a/.github/workflows/seed-issues.yml +++ b/.github/workflows/seed-issues.yml @@ -44,7 +44,7 @@ jobs: echo "Dry run: $DRY_RUN" shopt -s nullglob - FILES=(.github/seed-issues/*.md) + FILES=(.github/seed-issues/[0-9][0-9]_*.md) if [ ${#FILES[@]} -eq 0 ]; then echo "No seed issues found in .github/seed-issues/" @@ -94,4 +94,4 @@ jobs: else gh "${GH_ARGS[@]}" fi - done \ No newline at end of file + done diff --git a/README.md b/README.md index 9298498..800e4b9 100644 --- a/README.md +++ b/README.md @@ -162,6 +162,16 @@ Per il resto: I riferimenti rapidi sono raccolti in `docs/lab_links.md`. +## Seed issue del template + +Questo template include anche una piccola libreria di seed issue in `.github/seed-issues/`. + +Non vanno aperte tutte in blocco: + +- servono come base da adattare al dataset reale +- conviene usarne poche, solo quando corrispondono a un blocco o a un prossimo passo concreto +- il workflow `seed-issues.yml` crea issue solo dai file numerati `NN_nome.md` + ## 🌍 Archivio pubblico Se il progetto pubblica artifact in un archivio pubblico DataCivicLab su Drive, il flusso consigliato e: diff --git a/docs/contributing.md b/docs/contributing.md index 80c85a8..c5b4e8d 100644 --- a/docs/contributing.md +++ b/docs/contributing.md @@ -54,6 +54,12 @@ toolkit status --dataset --year --latest --config dataset.yml - Project board o milestone della repo, se presenti: avanzamento e priorita - Discord o altri canali veloci del team: utili per scambio rapido, non come fonte canonica +Regola pratica: + +- non aprire issue grandi di lifecycle "per principio" +- usa poche issue piccole, legate a un blocco reale o al prossimo passo concreto +- le seed issue in `.github/seed-issues/` servono come base da adattare, non come pacchetto da aprire in blocco + ## Publish su Drive Se il progetto usa un archivio pubblico su Drive, la pubblicazione va fatta dopo `run all` e `validate all`, non durante il run. @@ -95,14 +101,16 @@ Quando lavori per layer invece che con `run all`, usa questa regola semplice: - `toolkit inspect paths --config dataset.yml --year --json` ti dice dove leggerli - notebook e controlli manuali devono leggere i path restituiti, non ricostruirli a mano -## Fasi operative +## Fasi operative leggere - kickoff e contratto: `dataset.yml`, `README.md`, `tests/test_contract.py` - sources e raw: `dataset.yml`, `docs/sources.md`, `docs/decisions.md`, `notebooks/01_inspect_raw.ipynb` - clean: `sql/clean.sql`, `dataset.yml`, `notebooks/02_inspect_clean.ipynb` - mart: `sql/mart/*.sql`, `dataset.yml`, `notebooks/03_explore_mart.ipynb` -- qa: `tests/test_contract.py`, `.github/workflows/ci.yml`, `notebooks/04_quality_checks.ipynb` -- dashboard/export: `dashboard/`, `README.md`, `notebooks/05_dashboard_export.ipynb` +- release e handoff: `README.md`, `docs/overview.md`, `docs/data_dictionary.md` +- maintenance: `dataset.yml`, `sql/`, `docs/`, `tests/test_contract.py` + +Queste fasi non sono una catena rigida: spesso bastano 2-4 issue piccole per far avanzare davvero il progetto. ## Checklist lifecycle @@ -112,9 +120,8 @@ Quando lavori per layer invece che con `run all`, usa questa regola semplice: | Sources/RAW | `dataset.yml`, `docs/sources.md`, `docs/decisions.md` | `toolkit run raw --config dataset.yml`, poi `toolkit inspect paths --config dataset.yml --year --json` | `01_inspect_raw.ipynb` | | CLEAN | `sql/clean.sql`, `dataset.yml`, `docs/data_dictionary.md` | `toolkit run clean --config dataset.yml`, poi `toolkit inspect paths --config dataset.yml --year --json` | `02_inspect_clean.ipynb` | | MART | `sql/mart/*.sql`, `dataset.yml` | `toolkit run mart --config dataset.yml`, poi `toolkit inspect paths --config dataset.yml --year --json` | `03_explore_mart.ipynb` | -| QA | `tests/test_contract.py`, `.github/workflows/ci.yml` | `toolkit validate all --config dataset.yml` | `04_quality_checks.ipynb` | -| Output pubblico | `dashboard/`, `README.md`, `scripts/publish_to_drive.py` | `maintainer-only: py scripts/publish_to_drive.py --config dataset.yml --drive-root "" --dry-run` | `05_dashboard_export.ipynb` | | Release | `README.md`, `docs/overview.md`, `docs/data_dictionary.md` | `toolkit status --dataset --year --latest --config dataset.yml` | `00_quickstart.ipynb` | +| Maintenance | `dataset.yml`, `sql/`, `docs/`, `tests/test_contract.py` | `toolkit run all --config dataset.yml` | `01_inspect_raw.ipynb`, `02_inspect_clean.ipynb`, `03_explore_mart.ipynb` | I notebook usano `toolkit inspect paths --config dataset.yml --year --json` come contratto stabile per localizzare gli output.