Setup locale

Guida per chi vuole lavorare sui dati o sul codice di DataCivicLab.

Due percorsi, non uno solo:

  1. Contributore su un progetto — cloni una repo, ti basta quella (consigliato)
  2. 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:

ProgettoRepo
Spesa pubblicadataciviclab/open-siope
Costituzionedataciviclab/costituzione-italiana
Aiuti di Statodataciviclab/rna-aiuti-stato
Elenco completodataciviclab org

Fork e PR

  1. Fork sul repo che ti serve
  2. Clona il tuo fork
  3. Upstream: git remote add upstream https://github.com/dataciviclab/<repo>.git
  4. Branch — mai lavorare su main
  5. 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 Makefile alla root (auto-discovery find)? Sostituiscilo col forwarder: i target test/lint/info ora sono nel Makefile del contratto, guidati dai path reali del workspace (ws.py print-paths).

Comandi workspace

ComandoCosa fa
make helpMappa comandi (lifecycle + dev loop)
make setup.venv + install core/essential dal contratto
make clone-coreClona core + infra essenziali
make clone SLUG=open-siopeClona un repo dati dal contratto
make statusCosa è clonato / cosa manca
make doctorValida layout vs workspace.toml
make env.env.example → .env se manca
make mcpGenera .mcp.json per agenti AI
make test / make lintTest e lint su tutti i repo Python del contratto
make contributorIstruzioni 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