diff --git a/.editorconfig b/.editorconfig new file mode 100644 index 0000000..4d761dd --- /dev/null +++ b/.editorconfig @@ -0,0 +1,10 @@ +root = true + +[*] +charset = utf-8 +end_of_line = lf +insert_final_newline = true +trim_trailing_whitespace = true + +[*.md] +trim_trailing_whitespace = false diff --git a/.gitattributes b/.gitattributes new file mode 100644 index 0000000..6313b56 --- /dev/null +++ b/.gitattributes @@ -0,0 +1 @@ +* text=auto eol=lf diff --git a/.github/DISCUSSION_TEMPLATE/datasets.yml b/.github/DISCUSSION_TEMPLATE/datasets.yml index 257e977..f1952a9 100644 --- a/.github/DISCUSSION_TEMPLATE/datasets.yml +++ b/.github/DISCUSSION_TEMPLATE/datasets.yml @@ -8,21 +8,21 @@ body: - type: input id: fonte attributes: - label: 🔗 Fonte ufficiale + label: Fonte ufficiale placeholder: URL dataset - type: textarea id: descrizione attributes: - label: 🧾 Cosa contiene? + label: Cosa contiene? description: Descrizione sintetica del dataset - type: textarea id: struttura attributes: - label: 🏗 Struttura dati + label: Struttura dati - type: textarea id: criticita attributes: - label: ⚠ Limiti o rischi + label: Limiti o rischi diff --git a/.github/DISCUSSION_TEMPLATE/domande.yml b/.github/DISCUSSION_TEMPLATE/domande.yml index 46931b8..dd42e0e 100644 --- a/.github/DISCUSSION_TEMPLATE/domande.yml +++ b/.github/DISCUSSION_TEMPLATE/domande.yml @@ -3,14 +3,23 @@ body: - type: textarea id: perche attributes: - label: 🎯 Perché questa domanda è rilevante? + label: Perché questa domanda è rilevante? + description: Spiega il problema pubblico o civico che vuoi capire meglio. - type: textarea id: metriche attributes: - label: 📏 Metriche possibili + label: Metriche possibili + description: Indica dati, indicatori o confronti che potrebbero aiutare a rispondere. - type: textarea id: ipotesi attributes: - label: 🧠 Ipotesi iniziali + label: Ipotesi iniziali + description: Se hai già un'idea, esplicitala. Se non l'hai, va bene comunque. + + - type: textarea + id: next_step + attributes: + label: Se diventa lavoro concreto + description: Indica in quale repo dovrebbe nascere una issue operativa e quale sarebbe il primo output utile. diff --git a/.github/DISCUSSION_TEMPLATE/metodo.yml b/.github/DISCUSSION_TEMPLATE/metodo.yml index eff980e..623bba2 100644 --- a/.github/DISCUSSION_TEMPLATE/metodo.yml +++ b/.github/DISCUSSION_TEMPLATE/metodo.yml @@ -8,20 +8,20 @@ body: - type: textarea id: contesto attributes: - label: 🧩 Contesto + label: Contesto required: true - type: textarea id: scelta attributes: - label: ⚙ Proposta metodologica + label: Proposta metodologica - type: textarea id: alternative attributes: - label: 🔄 Alternative valutate + label: Alternative valutate - type: textarea id: impatto attributes: - label: 📊 Impatto su replicabilità e confronto + label: Impatto su replicabilità e confronto diff --git a/.github/DISCUSSION_TEMPLATE/presentazioni.yml b/.github/DISCUSSION_TEMPLATE/presentazioni.yml index a9ce629..68f3b9c 100644 --- a/.github/DISCUSSION_TEMPLATE/presentazioni.yml +++ b/.github/DISCUSSION_TEMPLATE/presentazioni.yml @@ -8,27 +8,27 @@ body: - type: textarea id: bio attributes: - label: 👤 Chi sei - description: Breve bio (2–3 righe). + label: Chi sei + description: Breve bio (2-3 righe). validations: required: true - type: textarea id: competenze attributes: - label: 🧠 Competenze + label: Competenze description: Dati, analisi, visualizzazione, metodo, altro. - type: textarea id: interessi attributes: - label: 💡 Cosa ti interessa + label: Cosa ti interessa description: Temi civici, dataset, progetti. - type: dropdown id: disponibilita attributes: - label: ⏱️ Disponibilità + label: Disponibilità options: - Occasionale - Continuativa @@ -36,5 +36,5 @@ body: - type: textarea id: contributo attributes: - label: 🤝 Come vorresti contribuire - description: Discussioni, analisi, doc, QA, altro. \ No newline at end of file + label: Come vorresti contribuire + description: Discussioni, analisi, doc, QA, altro. diff --git a/.github/DISCUSSION_TEMPLATE/proposte.yml b/.github/DISCUSSION_TEMPLATE/proposte.yml index 4edebb7..9e2b58f 100644 --- a/.github/DISCUSSION_TEMPLATE/proposte.yml +++ b/.github/DISCUSSION_TEMPLATE/proposte.yml @@ -8,7 +8,7 @@ body: - type: textarea id: domanda attributes: - label: 🎯 Domanda civica + label: Domanda civica description: Una sola frase chiara. validations: required: true @@ -16,7 +16,7 @@ body: - type: textarea id: obiettivo attributes: - label: 📌 Obiettivo del progetto + label: Obiettivo del progetto description: Cosa produrremo e per chi? validations: required: true @@ -24,13 +24,13 @@ body: - type: textarea id: dataset attributes: - label: 📊 Dataset coinvolti - description: Dataset — Fonte — Periodo — Livello. + label: Dataset coinvolti + description: Dataset - Fonte - Periodo - Livello. - type: dropdown id: output attributes: - label: 🛠️ Output previsto + label: Output previsto options: - Dashboard - Report @@ -40,7 +40,7 @@ body: - type: dropdown id: complessita attributes: - label: ⏱️ Complessità stimata + label: Complessità stimata options: - Bassa - Media @@ -49,9 +49,9 @@ body: - type: dropdown id: stato attributes: - label: 🚦 Stato + label: Stato options: - Idea - In discussione - Pronto per Issue - - In corso \ No newline at end of file + - In corso diff --git a/.github/ISSUE_TEMPLATE/bug.md b/.github/ISSUE_TEMPLATE/bug.md index 31a2b2b..20ccc58 100644 --- a/.github/ISSUE_TEMPLATE/bug.md +++ b/.github/ISSUE_TEMPLATE/bug.md @@ -18,4 +18,4 @@ Descrizione chiara e sintetica del bug. Repo / file / notebook / ambiente ## 🎯 Comportamento atteso -Cosa dovrebbe succedere invece? \ No newline at end of file +Cosa dovrebbe succedere invece? diff --git a/.github/ISSUE_TEMPLATE/config.yml b/.github/ISSUE_TEMPLATE/config.yml index e4b3db1..e32457e 100644 --- a/.github/ISSUE_TEMPLATE/config.yml +++ b/.github/ISSUE_TEMPLATE/config.yml @@ -1,5 +1,5 @@ blank_issues_enabled: true contact_links: - name: 💬 Discussions - url: https://github.com/dataciviclab/dataciviclab/discussions - about: Per idee, metodo e confronto usa le Discussions. \ No newline at end of file + url: https://github.com/orgs/dataciviclab/discussions + about: Per idee, orientamento e confronto usa le Discussions dell'organizzazione. diff --git a/.github/ISSUE_TEMPLATE/task.md b/.github/ISSUE_TEMPLATE/task.md index 5db7755..f812504 100644 --- a/.github/ISSUE_TEMPLATE/task.md +++ b/.github/ISSUE_TEMPLATE/task.md @@ -17,4 +17,6 @@ Perché è necessario? - [ ] ## 🔗 Collegamenti -Issue correlate / Discussion / PR \ No newline at end of file +Issue correlate / Discussion / PR + +Se il task nasce da una domanda civica o da una proposta di analisi, collega qui la Discussion di origine. diff --git a/.github/workflows/templates.yml b/.github/workflows/templates.yml new file mode 100644 index 0000000..cc8cd08 --- /dev/null +++ b/.github/workflows/templates.yml @@ -0,0 +1,56 @@ +name: Templates + +on: + push: + branches: + - main + pull_request: + +jobs: + validate-templates: + runs-on: ubuntu-latest + steps: + - name: Checkout + uses: actions/checkout@v4 + + - name: Set up Python + uses: actions/setup-python@v5 + with: + python-version: "3.11" + + - name: Install PyYAML + run: python -m pip install pyyaml + + - name: Validate discussion and issue templates + run: | + python - <<'PY' + from pathlib import Path + import yaml + + root = Path(".").resolve() / ".github" + errors = [] + + for path in sorted((root / "DISCUSSION_TEMPLATE").glob("*.yml")): + try: + yaml.safe_load(path.read_text(encoding="utf-8")) + except Exception as exc: + errors.append(f"{path.relative_to(root.parent)}: {exc}") + + for path in sorted((root / "ISSUE_TEMPLATE").glob("*.md")): + text = path.read_text(encoding="utf-8") + if not text.startswith("---"): + errors.append(f"{path.relative_to(root.parent)}: missing frontmatter start") + continue + parts = text.split("---", 2) + if len(parts) < 3: + errors.append(f"{path.relative_to(root.parent)}: invalid frontmatter") + continue + frontmatter = parts[1] + try: + yaml.safe_load(frontmatter) + except Exception as exc: + errors.append(f"{path.relative_to(root.parent)}: {exc}") + + if errors: + raise SystemExit("Template validation failed:\n" + "\n".join(errors)) + PY diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md index 2ba81cb..9add795 100644 --- a/CODE_OF_CONDUCT.md +++ b/CODE_OF_CONDUCT.md @@ -1,15 +1,21 @@ -# Code of Conduct +# 🌿 Code of Conduct -Il DataCivicLab è uno spazio collaborativo e rispettoso. +DataCivicLab vuole essere uno spazio pubblico, rispettoso e utile. Ci aspettiamo: -- rispetto reciproco -- confronto basato su fatti e dati -- zero attacchi personali -Comportamenti inaccettabili: -- molestie -- discriminazioni -- trolling +- rispetto per le persone e per il loro tempo +- critiche rivolte alle idee, non alle persone +- confronto chiaro, documentato e in buona fede +- attenzione a linguaggio, contesto e accessibilita' -I maintainer possono intervenire per tutelare la community. +Non sono accettati: + +- insulti, attacchi personali o intimidazioni +- discriminazioni o molestie +- comportamenti deliberatamente ostili o distruttivi +- pubblicazione di dati personali, credenziali o informazioni sensibili + +I maintainer possono moderare discussioni, chiudere thread o limitare la partecipazione quando serve a proteggere la qualita' dello spazio comune. + +Per segnalare un problema di comportamento, usa i riferimenti indicati in [SUPPORT.md](SUPPORT.md). diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index a1bff89..39e291c 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,120 +1,72 @@ -# 🤝 Come contribuire al DataCivicLab +# 🤝 Contributing -Questo è un progetto civico aperto. -Puoi contribuire anche senza far parte dell’organizzazione. +Grazie per voler contribuire a DataCivicLab. -## 🧭 1) Guardare e capire (senza fare nulla) +Questa guida serve a orientarti senza farti studiare tutto prima. -Puoi: +Il Lab e' aperto, ma non caotico. +C'e' un posto giusto per ogni cosa. -* leggere i repository pubblici -* guardare gli output (dashboard, report) -* capire **come lavoriamo davvero** +## 🌱 Da dove partire -👉 Non serve iscriversi. -👉 Non serve essere “esperti”. +Se vuoi capire il quadro generale, parti dalla repository `dataciviclab`. -Questo è già contributo: **trasparenza**. +Se vuoi contribuire all'organizzazione nel suo insieme: +- parti dalle [Discussions](https://github.com/orgs/dataciviclab/discussions) dell'org +- guarda [Open Board](https://github.com/orgs/dataciviclab/projects/5) per il lavoro in corso +- guarda [Roadmap](https://github.com/orgs/dataciviclab/projects/2) per capire direzione, progetti e milestone -## 💡 2) Proporre un problema o una domanda civica +Se invece vuoi contribuire a un repository specifico, usa questa regola semplice: -Puoi: +- `toolkit`: se vuoi lavorare sul motore tecnico della pipeline dati +- `project-template`: se vuoi migliorare il template operativo da cui nascono i repo dataset +- repo progetto o dataset: se vuoi lavorare su un progetto concreto +- `.github`: se vuoi migliorare policy condivise, onboarding, template o profilo pubblico GitHub -* aprire una **Discussion** -* proporre una **domanda concreta** -* segnalare un **dataset pubblico** +In ogni caso: -Esempio: +- leggi il `README.md` del repository +- controlla issue e discussions aperte +- verifica se esistono istruzioni locali aggiuntive -> “Esiste un modo per capire come vengono spesi questi fondi?” +Non serve essere esperti del motore per partecipare. +Puoi anche partire da una domanda, da una correzione piccola o da un problema ben descritto. -Non serve la soluzione. -Serve una **buona domanda**. +## 🔄 Flusso minimo +Nell'organizzazione usiamo un flusso semplice: -## 📊 3) Segnalare o mappare dataset pubblici +1. apri o trovi una Discussion se serve chiarire il contesto +2. apri o prendi in carico una Issue quando il lavoro e' definito +3. proponi il cambiamento con una Pull Request -Se conosci: +Le issue servono a rendere il lavoro visibile. +Le pull request servono a far entrare i cambiamenti in modo chiaro e revisionabile. -* una banca dati pubblica -* un open data poco usato -* una fonte istituzionale utile +## 🧩 Cosa usare e quando -Puoi: +- `Discussions`: domande, idee, confronto iniziale, orientamento +- `Issues`: lavoro concreto da fare o problema da risolvere +- `Pull requests`: proposta di modifica pronta da rivedere +- `Open Board`: vista pubblica del lavoro in corso +- `Roadmap`: vista pubblica di direzione, progetti e prossime tappe +- `Discord`: scambio veloce o informale, non traccia canonica -* segnalarla in Discussion -* indicare link, periodo, ente +GitHub resta il posto dove deve restare la traccia utile. -👉 Questo spesso è il **vero punto di partenza**. +GitHub Projects puo' essere usato dai maintainer per organizzare il lavoro, ma non sostituisce issue e pull request come traccia pubblica. +## ✅ Prima di aprire una PR -## 🛠️ 4) Migliorare qualcosa che già esiste +- controlla se esiste gia' una issue o discussion collegata +- tieni il cambiamento piccolo e leggibile +- spiega il perche', non solo il cosa +- se la modifica e' specifica di un repo, segui le regole di quel repo -Se vedi: +## 🧱 Confini di questa repo -* un errore -* un limite -* una spiegazione poco chiara - -Puoi: - -* aprire una **Issue** -* oppure una **Pull Request** (anche piccola) - -Non serve rifare tutto. -Anche migliorare una frase, un grafico o una query è contributo. - - -## 🔍 5) Fare revisione e QA - -Anche senza scrivere codice puoi: - -* verificare se i numeri tornano -* controllare se il metodo è chiaro -* segnalare ambiguità - -👉 Il **controllo civico** è anche questo. - - -## 📣 6) Usare e diffondere gli output - -Puoi: - -* usare una dashboard -* citarla in un articolo -* condividerla con altri -* usarla per fare domande a un’amministrazione - -Questo è **impatto reale**, non marketing. - - -## 🚀 7) Entrare in un progetto (se vuoi) - -Se vuoi contribuire attivamente: - -* guardi le **Issue aperte** -* scegli un task chiaro -* ti assegni o commenti - -Non serve “essere dentro”. -Conta **quello che fai**, non il badge. - - -# 🧠 Regole semplici (per tutti) - -* Nessuno è obbligato a fare nulla -* Nessuno decide da solo -* Le idee diventano realtà solo se producono output -* Tutto è pubblico e verificabile - - -# 🧩 In una frase - -> Puoi osservare, proporre, migliorare, verificare o usare. -> Se qualcosa ti sembra utile o sbagliato, puoi dirlo e mostrarlo. - -Questo è il DataCivicLab. - -Prima di iniziare, leggi il [WORKFLOW.md](WORKFLOW.md). +La repository `.github` definisce il layer comune GitHub dell'organizzazione. +Non descrive il metodo dati, la pipeline tecnica o la struttura operativa dei repository dataset. +Per quei contenuti, fai riferimento ai repository dedicati. diff --git a/DISCUSSIONS.md b/DISCUSSIONS.md new file mode 100644 index 0000000..b5c6278 --- /dev/null +++ b/DISCUSSIONS.md @@ -0,0 +1,34 @@ +# 💬 Discussions e Projects + +Le GitHub Discussions sono il posto giusto quando serve parlare prima di implementare. +Sono il posto giusto anche quando non hai ancora capito tutto ma vuoi lasciare una traccia chiara. + +Usale per: + +- fare una domanda +- proporre un'idea +- chiedere orientamento sul repository giusto +- aprire un confronto pubblico prima di trasformarlo in issue + +Non usarle per: + +- segnalare vulnerabilita' +- sostituire una pull request +- tenere nascosto lavoro operativo che dovrebbe stare in una issue + +Se da una discussion emerge un lavoro concreto, apri o collega una issue. + +## 📌 Projects pubblici + +In DataCivicLab usiamo due GitHub Projects pubblici: + +- [`Open Board`](https://github.com/orgs/dataciviclab/projects/5): lavoro in corso, task, issue, blocchi e attivita' operative +- [`Roadmap`](https://github.com/orgs/dataciviclab/projects/2): direzione pubblica, progetti, milestone e prossime tappe + +Usali per orientarti, non per sostituire issue e pull request. + +- se vuoi capire cosa sta succedendo adesso, guarda `Open Board` +- se vuoi capire dove stiamo andando, guarda `Roadmap` +- se vuoi parlare con calma e lasciare traccia, usa `Discussions` + +Discord e' utile per scambio veloce o eventi, ma la traccia utile deve restare su GitHub. diff --git a/GOVERNANCE.md b/GOVERNANCE.md index ba334a8..1ccf917 100644 --- a/GOVERNANCE.md +++ b/GOVERNANCE.md @@ -1,22 +1,38 @@ -# ⚖️ Governance DataCivicLab +# 🧱 Governance -Questo è un progetto civico e uno spazio comune. -Non c’è un capo e nulla è definitivo. +Questo documento riguarda solo la collaborazione cross-repo su GitHub. -Il metodo e il sistema si costruiscono attraverso: -- contributi concreti -- output pubblici -- miglioramenti incrementali +## 📘 Cosa decide questa repo -Chi contribuisce se ne prende cura. -Le decisioni seguono il metodo, non le opinioni. +`.github` definisce gli standard condivisi dell'organizzazione per: -Nel DataCivicLab usiamo GitHub Teams solo per gestire permessi tecnici. +- onboarding contributor +- template e flussi GitHub comuni +- regole minime di collaborazione pubblica +- supporto, moderazione e sicurezza -- I maintainer sono custodi del metodo e dell’ordine minimo, non capi. +Non definisce: -- I contributor producono lavoro e output. +- roadmap del Lab +- priorita' di prodotto o di ricerca +- metodo dati +- scelte tecniche del `toolkit` -- Gli observer osservano e imparano. +## 👥 Ruoli pratici -I ruoli non sono fissi e possono cambiare nel tempo, in base ai contributi reali. +- `Maintainer`: cura ordine, moderazione, review e coerenza minima tra repository +- `Contributor`: propone, discute e implementa cambiamenti +- `Observer`: legge, segnala, commenta e porta contesto + +I ruoli non sono identita' fisse. Contano responsabilita' e contributi concreti. + +## 🗂️ Come prendiamo decisioni su GitHub + +Quando possibile: + +1. il confronto parte in una Discussion o in una issue +2. il cambiamento viene proposto in modo tracciabile +3. la decisione finale viene resa visibile nella pull request o nell'issue collegata + +Se una decisione riguarda un solo repository, vale la documentazione di quel repository. +Se invece riguarda il modo in cui l'organizzazione usa GitHub, il riferimento canonico e' questa repo. diff --git a/PULL_REQUEST_TEMPLATE.md b/PULL_REQUEST_TEMPLATE.md index 53d3d26..d08f474 100644 --- a/PULL_REQUEST_TEMPLATE.md +++ b/PULL_REQUEST_TEMPLATE.md @@ -1,36 +1,39 @@ -# 🧾 Pull Request – DataCivicLab +## Sintesi + +Spiega in poche righe cosa cambia e perche'. + +## Contesto collegato -## 🔗 Issue collegata Closes # -## 🎯 Contesto -Spiega brevemente perché questa PR è necessaria. - -## ⚙️ Cosa cambia -Descrivi in modo sintetico le modifiche introdotte: -- punto 1 -- punto 2 -- punto 3 - -## 📊 Impatto su dati / metodo / dashboard -Indicare se questa PR impatta: -- [ ] RAW -- [ ] CLEAN -- [ ] MART -- [ ] Dashboard -- [ ] Metodo -- [ ] Documentazione -- [ ] Bugfix -- [ ] Nessun impatto dati - -Spiega eventuali effetti su replicabilità o confrontabilità. - -## 🧪 QA Checklist -- [ ] Ho testato il codice / notebook -- [ ] Non rompe pipeline esistenti -- [ ] Naming coerente (snake_case, convenzioni Lab) -- [ ] Documentazione aggiornata -- [ ] Ho collegato l’issue corretta - -## 📝 Note per i reviewer -Segnala punti critici o aspetti che richiedono particolare attenzione \ No newline at end of file +## Cosa cambia + +- +- +- + +## Impatto + +Segna solo quello che si applica. + +- [ ] Documentazione o testi +- [ ] Policy GitHub o template +- [ ] Codice o automazioni +- [ ] Pipeline dati o trasformazioni +- [ ] Contenuti o metadati di dataset +- [ ] Nessun impatto visibile per chi usa il repository + +## Verifica + +Spiega come hai verificato il cambiamento. Se non serve, scrivi `N/A`. + +## Controlli + +- [ ] Questa PR e' nel repository giusto +- [ ] Ho collegato issue o discussion quando serve +- [ ] Ho verificato l'impatto su documentazione, codice o dati +- [ ] Ho aggiornato solo quello che era davvero necessario + +## Note per chi revisiona + +Segnala qui rischi, limiti o punti su cui vuoi un controllo mirato. diff --git a/README.md b/README.md index 742cef5..7df41de 100644 --- a/README.md +++ b/README.md @@ -1,28 +1,43 @@ -# DataCivicLab – Governance & Workflow +# 🧭 DataCivicLab GitHub Commons -Questo repository definisce le **regole operative comuni** a tutti i progetti del DataCivicLab. +Questa repository raccoglie i file condivisi che definiscono l'esperienza GitHub comune di `dataciviclab`. -Qui non ci sono dati, codice o dashboard. -Qui ci sono: -- come lavoriamo -- come contribuiamo -- come prendiamo decisioni -- come manteniamo qualità e coerenza +Non e' l'hub pubblico del Lab. +E' il posto in cui teniamo ordine su GitHub. -## 📌 File principali -- `WORKFLOW.md` → come funziona il lavoro quotidiano -- `CONTRIBUTING.md` → come iniziare a contribuire -- `ISSUE_TEMPLATE/` → come aprire Issue utili -- `PULL_REQUEST_TEMPLATE.md` → come proporre cambiamenti -- `CODE_OF_CONDUCT.md` → regole di comportamento -- `SECURITY.md` → gestione segnalazioni sensibili +Qui vivono: -## 🧭 Regola base -> Se una regola vale per più di un progetto, vive qui. +- community health files +- policy comuni di collaborazione +- template per issue, pull request e discussions +- profilo pubblico dell'organizzazione +- istruzioni minime su supporto, sicurezza e canali +- orientamento leggero su Discussions e Projects pubblici -Per regole specifiche di un progetto, fai riferimento al repository dedicato. +Qui non vivono: -## 📘 Regole operative +- cataloghi dataset +- roadmap del Lab +- metodo dati +- documentazione tecnica del toolkit +- bootstrap operativo dei repository dataset -- [Workflow di lavoro](WORKFLOW.md) -- [Come contribuire](CONTRIBUTING.md) +Per il contesto generale del Lab e l'indice dell'ecosistema, il punto di ingresso resta la repository `dataciviclab`. +Per domande e confronto pubblico trasversale, il punto di ingresso resta [GitHub Discussions](https://github.com/orgs/dataciviclab/discussions) dell'organizzazione. +Per seguire il lavoro in corso, il riferimento e' [Open Board](https://github.com/orgs/dataciviclab/projects/5). +Per vedere direzione, progetti e milestone, il riferimento e' [Roadmap](https://github.com/orgs/dataciviclab/projects/2). + +## Flusso consigliato + +Su GitHub cerchiamo di tenere distinti i livelli: + +- **Discussions** per formulare domande civiche, proposte, interpretazioni e bisogno informativo +- **Issues** per il lavoro operativo che ne deriva +- **PR** per le modifiche effettive a codice, documentazione o progetto + +In breve: + +`Discussion -> Issue -> PR` + +Non tutte le issue nascono da una discussion. +Ma quando il punto di partenza e una domanda civica o una proposta di analisi, la discussion e il posto giusto per iniziare. diff --git a/SECURITY.md b/SECURITY.md index ab3e95b..c5a0aac 100644 --- a/SECURITY.md +++ b/SECURITY.md @@ -1,12 +1,18 @@ -# Security Policy +# Security -Non pubblicare: -- dati personali non anonimizzati -- credenziali -- informazioni sensibili +Se trovi una vulnerabilita', non aprire una issue pubblica. + +Usa GitHub Security Advisories se disponibili per il repository coinvolto. Se non sono disponibili, contatta in privato i maintainer del repository interessato prima di pubblicare dettagli. + +Usa i canali pubblici solo per: -Per segnalazioni di sicurezza: -- aprire una Issue privata se possibile -- oppure contattare i maintainer +- domande generali di sicurezza +- chiarimenti non sensibili +- miglioramenti di documentazione -Grazie per aiutarci a mantenere il Lab sicuro. +Non pubblicare mai: + +- credenziali +- token +- dati personali +- dettagli che facilitano uno sfruttamento immediato del problema diff --git a/SUPPORT.md b/SUPPORT.md new file mode 100644 index 0000000..706cbc8 --- /dev/null +++ b/SUPPORT.md @@ -0,0 +1,30 @@ +# 🆘 Support + +Non serve sapere tutto subito. +Serve solo scegliere il canale giusto per quello che ti serve. + +## 📍 Dove scrivere + +- [`GitHub Discussions`](https://github.com/orgs/dataciviclab/discussions): domande, idee, orientamento e confronto pubblico nell'org `dataciviclab` +- `Issues`: bug, problemi chiari, attivita' da svolgere +- `Pull requests`: proposta di modifica gia' pronta +- [`Open Board`](https://github.com/orgs/dataciviclab/projects/5): per vedere il lavoro in corso, i task aperti e i blocchi +- [`Roadmap`](https://github.com/orgs/dataciviclab/projects/2): per vedere direzione pubblica, progetti e milestone +- [`Discord`](https://discord.gg/rAHpuTrYK3): scambio rapido, community ed eventi, ma non fonte canonica +- `LinkedIn`: aggiornamenti pubblici, non supporto operativo + +Se hai un dubbio e non sai dove andare, la scelta piu' sicura e' iniziare da GitHub Discussions. + +## 📝 Prima di aprire qualcosa + +- controlla se esiste gia' una issue o discussion simile +- scegli il repository corretto +- se ti serve solo orientamento, parti dalle Discussions dell'organizzazione +- se vuoi capire cosa si sta facendo adesso, guarda `Open Board` +- se vuoi capire dove stiamo andando, guarda `Roadmap` +- se il tema riguarda metodo dati o implementazione tecnica, usa il repository dedicato + +## 🔐 Sicurezza e comportamento + +- per vulnerabilita' o contenuti sensibili, vedi [SECURITY.md](SECURITY.md) +- per problemi di comportamento o moderazione, contatta i maintainer del repository coinvolto diff --git a/WORKFLOW.md b/WORKFLOW.md deleted file mode 100644 index ced4b23..0000000 --- a/WORKFLOW.md +++ /dev/null @@ -1,70 +0,0 @@ -# DataCivicLab – Workflow operativo - -Flusso ufficiale: -**Discussion → Issue → Branch → Pull Request → Merge** - ---- - -## 1. Discussions -Usate per: -- chiarire la domanda civica -- discutere dataset, limiti, metodo -- allinearci prima di lavorare - -Se non è chiaro **cosa fare**, apri una Discussion. - ---- - -## 2. Issues -Ogni lavoro nasce come Issue. - -Regole: -- una Issue = un obiettivo chiaro -- Issue piccole > Issue grandi -- se lavori su una Issue, assegnatela - ---- - -## 3. Branch -Non si lavora mai su `main`. - -Regola: -> **1 Issue = 1 Branch** - -Naming consigliato: -- `feature/...` -- `fix/...` -- `docs/...` - ---- - -## 4. Pull Request -Tutto passa da PR. - -Ogni PR: -- collega una Issue (`Closes #ID`) -- descrive cosa fa -- passa almeno una review - ---- - -## 5. Review & Merge -- 1 approvazione minima -- commenti risolti -- merge su `main` -- branch eliminato - ---- - -## 6. Ruoli -- **Observer**: legge e commenta -- **Contributor**: lavora su Issue e PR -- **Maintainer**: review, merge, qualità -- **Project Lead**: visione e decisioni finali - ---- - -## Regole d’oro -- Se non è una Issue, non esiste -- Se non è una PR, non entra in `main` -- Meglio PR piccole che PR mostro diff --git a/profile/README.md b/profile/README.md index 1643d20..fd40e3d 100644 --- a/profile/README.md +++ b/profile/README.md @@ -1,41 +1,32 @@ # 🌍 DataCivicLab -Un laboratorio open che trasforma dati pubblici in comprensione civica strutturata. +DataCivicLab e' uno spazio civico dove proviamo a rendere i dati pubblici piu' leggibili, utili e condivisibili. -Non produciamo opinioni. -Produciamo metodo. +Non serve capire tutto subito. +Serve solo capire da dove iniziare. -## 🧠 Cosa facciamo +## 🌱 Dove iniziare -- Analizziamo dataset pubblici ufficiali -- Costruiamo pipeline replicabili -- Standardizziamo trasformazioni dati -- Pubbliciamo dashboard verificabili -- Documentiamo ogni scelta metodologica +- [`dataciviclab`](https://github.com/dataciviclab/dataciviclab): hub pubblico e umano dell'organizzazione +- [`toolkit`](https://github.com/dataciviclab/toolkit): motore tecnico della pipeline dati +- [`project-template`](https://github.com/dataciviclab/project-template): base operativa dei repository dataset -## ⚙️ Come lavoriamo +## 🤝 Come partecipare -Domanda → Dataset → Pipeline → Analisi → Dashboard +- [GitHub Discussions](https://github.com/orgs/dataciviclab/discussions): per fare domande, proporre idee e parlare con calma lasciando traccia +- `Issues`: per il lavoro concreto da fare +- `Pull requests`: per proporre modifiche -Ogni progetto è documentato e versionato. +Se non sai ancora dove stare, parti dalle Discussions dell'organizzazione. -## 🏗 Repo principali +## 🔗 Canali -- `dataciviclab` → Governance e roadmap -- `project-template` → Struttura replicabile -- `toolkit` → Strumenti per pipeline dati (WIP) +- [GitHub Discussions](https://github.com/orgs/dataciviclab/discussions): confronto pubblico e asincrono +- [Open Board](https://github.com/orgs/dataciviclab/projects/5): lavoro in corso, task, blocchi e attivita' operative +- [Roadmap](https://github.com/orgs/dataciviclab/projects/2): direzione pubblica, progetti e milestone +- [Discord](https://discord.gg/rAHpuTrYK3): scambio veloce ed eventi, ma non fonte canonica +- LinkedIn: aggiornamenti pubblici e visibilita' esterna -## 🚀 Vuoi contribuire? +GitHub resta il posto dove deve restare la traccia utile. -Cerchiamo: - -- Data nerd -- Analisti civici -- Sviluppatori -- Curiosi strutturati - -👉 [Esplora le Discussions](https://github.com/orgs/dataciviclab/discussions) -👉 [Leggi il Manifesto](https://github.com/dataciviclab/dataciviclab/blob/main/docs/manifesto.md) -👉 [Unisciti alla community](https://discord.gg/rAHpuTrYK3) - -Costruiamo infrastruttura civica, non solo dashboard. +Per contribuire, parti dal canale o dal repository piu' vicino a quello che vuoi capire o migliorare.