Setup locale
Guida per chi vuole lavorare sui dati o sul codice di DataCivicLab.
Due percorsi, non uno solo:
- Contributore su un progetto — cloni una repo, ti basta quella (consigliato)
- Workspace multi-repo — core team o lavoro cross-repo (toolkit, incubator, …)
Se fai parte del core team, la guida interna è in lab-ops/operations/local-setup.md
(repo privata).
Requisiti
- Git
- Python 3.12+
- Make + bash (Linux, macOS, o Windows con WSL)
- VS Code (opzionale)
1. Contributore su un singolo progetto (consigliato)
Non serve clonare tutto il Lab. Ogni repo dati è un’unità verticale con il suo Makefile, pyproject e test.
git clone https://github.com/dataciviclab/open-siope.git
cd open-siope
# se il repo ha Makefile standard:
make setup && make check
# altrimenti:
python3 -m venv .venv && source .venv/bin/activate
pip install -e ".[dev]"
Sostituisci open-siope con il progetto che ti interessa. Esempi:
| Progetto | Repo |
|---|---|
| Spesa pubblica | dataciviclab/open-siope |
| Costituzione | dataciviclab/costituzione-italiana |
| Aiuti di Stato | dataciviclab/rna-aiuti-stato |
| Elenco completo | dataciviclab org |
Fork e PR
- Fork sul repo che ti serve
- Clona il tuo fork
- Upstream:
git remote add upstream https://github.com/dataciviclab/<repo>.git - Branch — mai lavorare su
main - PR dal fork al repo originale
Trovi le issue aperte sul repo del progetto o sulle good first issue nell’hub.
2. Workspace multi-repo (core / cross-repo)
Il workspace è una cartella con tanti clone (toolkit, infra, progetti per dominio). Non è un singolo git repo: il contratto path/ruoli vive nell’hub pubblico.
Layout canonico
dataciviclab-workspace/
toolkit/ # core
lab-connectors/ # core
dcl-mcp/ # core — MCP unico del Lab
infra/ # hub, incubator, SO, explorer, …
incubation/ # candidate
diritto-legge/ # domini (raggruppamento umano)
economia-finanza/
investimenti-territorio/
pubblica-amministrazione/
Makefile # forwarder → infra/dataciviclab/workspace/Makefile
.venv/
.env
I tool leggono workspace.toml (nell’hub, infra/dataciviclab/workspace/):
non hardcodano i nomi dei dominii — puoi riorganizzare le cartelle senza
rompere il contratto.
Setup
mkdir dataciviclab-workspace && cd dataciviclab-workspace
# 1. Hub (contiene contratto + docs)
git clone https://github.com/dataciviclab/dataciviclab.git infra/dataciviclab
# 2. Root Makefile = forwarder sull'hub (zero drift, si aggiorna con l'hub)
printf 'include infra/dataciviclab/workspace/Makefile\n' > Makefile
# 3. Repo core + infra essenziali
make clone-core
# 4. Ambiente Python + install editable
make setup
# 5. Verifica
make check
make doctor
make status
Tempo stimato: pochi minuti a seconda della connessione.
Hai già un vecchio
Makefilealla root (auto-discoveryfind)? Sostituiscilo col forwarder: i targettest/lint/infoora sono nel Makefile del contratto, guidati dai path reali del workspace (ws.py print-paths).
Comandi workspace
| Comando | Cosa fa |
|---|---|
make help | Mappa comandi (lifecycle + dev loop) |
make setup | .venv + install core/essential dal contratto |
make clone-core | Clona core + infra essenziali |
make clone SLUG=open-siope | Clona un repo dati dal contratto |
make status | Cosa è clonato / cosa manca |
make doctor | Valida layout vs workspace.toml |
make env | .env.example → .env se manca |
make mcp | Genera .mcp.json per agenti AI |
make test / make lint | Test e lint su tutti i repo Python del contratto |
make contributor | Istruzioni fork/upstream per i repo presenti |
Ambiente e secret
make env
# compila almeno GITHUB_TOKEN in .env
GITHUB_TOKEN è l’unico obbligatorio per MCP e automazioni GitHub.
MCP (agenti AI)
make mcp
Genera .mcp.json dalla root del workspace dal template hub
(scripts/mcp-servers.json): server unico dataciviclab
(dcl-mcp) + toolkit, SO,
legal-graph. Per OpenCode: copia il contenuto in opencode.json → mcp
(o usa _local/mcp/run-with-env.sh se presente).
Cosa fa ogni server e come configurarlo al di fuori del workspace: Agenti AI nel Lab.
Un progetto dati in più
make clone SLUG=giustizia-amministrativa
# oppure: make clone SLUG=legal-graph (se privato: clone manuale)
Il path effettivo è nel contratto (workspace.toml), es. diritto-legge/giustizia-amministrativa.
VS Code
code dataciviclab.code-workspace # se presente alla root
Setup manuale (senza Makefile workspace)
Se preferisci non usare il forwarder:
python3 -m venv .venv
source .venv/bin/activate
pip install -e lab-connectors
pip install -e "toolkit[parquet,dev]"
pip install --no-deps -e dcl-mcp
pip install --no-deps -e "infra/dataset-incubator[dev]"
pip install --no-deps -e "infra/source-observatory[dev]"
pip install -e lab-connectors # ripristina editable (git dep di dcl-mcp)
cp infra/dataciviclab/.env.example .env
Poi clona a mano i repo che ti servono nelle path del contratto.
Primo run (verifica pipeline)
Dopo make setup e il clone di un candidate:
toolkit --help
Oppure, da un repo dati:
cd economia-finanza/open-siope
make check
Script legacy
scripts/setup.sh è deprecato: path storici (analysis/, incubation/) non
corrispondono più al layout. Usa make setup / make clone-core come sopra.
Prossimi passi
- come-contribuire — percorsi per partecipare
- workspace/README.md — dettaglio contratto workspace
- Issue
good first issue— primo task