Pull Request
Il processo e i requisiti che descriviamo di seguito fungono da importanti linee guida essenziali per la gestione di un progetto Open Source e ci aiutano a prevenire sprechi di lavoro e a garantire l'integrità del codebase.
Setup per lo sviluppo locale
Clona il repository e configura l'intero ambiente di sviluppo in un unico passo:
git clone https://github.com/PythonWoods/zenzic.git
cd zenzic
nox -s dev
nox -s dev esegue uv sync --group dev (installando tutti i gruppi di dipendenze — test,
lint, docs e release tooling) e poi installa gli hook pre-commit. È il comando di setup
canonico one-shot; eseguilo una volta dopo il clone.
Per un setup più granulare o se non hai ancora nox installato, usa direttamente uv:
- uv (raccomandato)
- pip
git clone https://github.com/PythonWoods/zenzic.git
cd zenzic
uv sync --group dev
source .venv/bin/activate # Windows: .venv\Scripts\activate
uv risolve le dipendenze molto più velocemente di pip e
produce un ambiente riproducibile tramite uv.lock. Preferito per tutto il lavoro di
sviluppo.
git clone https://github.com/PythonWoods/zenzic.git
cd zenzic
python -m venv .venv
source .venv/bin/activate # Windows: .venv\Scripts\activate
pip install -e .
pip install pytest pytest-cov ruff mypy pre-commit reuse mkdocs-material mkdocstrings[python] mkdocs-minify-plugin mkdocs-static-i18n
Gruppi di dipendenze
Zenzic usa i gruppi di dipendenze PEP 735 per mantenere la CI veloce installando solo ciò di cui ogni job ha bisogno. I gruppi sono:
| Gruppo | Contenuto | Quando usarlo |
|---|---|---|
test | pytest, pytest-cov, hypothesis, mutmut | Esecuzione della suite di test |
lint | ruff, mypy, pre-commit, reuse | Linting e type checking |
docs | Stack MkDocs (mkdocs-material, ecc.) | Build della documentazione |
release | nox, bump-my-version, pip-audit | Rilasci e audit |
dev | Tutti i precedenti (aggregatore) | Sviluppo locale |
Installa un singolo gruppo quando hai bisogno solo di un sottoinsieme:
uv sync --group test # solo pytest
uv sync --group lint # solo ruff + mypy
uv sync --group docs # dipendenze build documentazione
uv sync --group dev # tutto (raccomandato per i contributori)
Con un'installazione editabile, il binario zenzic nel tuo PATH esegue
sempre il sorgente su cui stai lavorando. Puoi validare la documentazione del
repository in qualsiasi momento:
zenzic check all # tutti e sette i controlli
zenzic check references # include la valutazione delle [[custom_rules]]
pytest # suite di test completa (profilo Hypothesis dev — 50 esempi)
Per eseguire la suite di test con il profilo Hypothesis ci (500 esempi),
usa just test-full o imposta direttamente la variabile d'ambiente:
just test-full
# oppure
HYPOTHESIS_PROFILE=ci pytest
Gli utenti finali eseguono uvx zenzic check all — nessun clone,
nessuna installazione, zero attrito. È il punto di ingresso documentato
nelle guide rivolte agli utenti.
I contributori clonano il repo e installano in modalità editabile come
mostrato sopra. Il binario zenzic nel virtualenv attivato è quello da
usare — non uvx, che scaricherebbe la versione PyPI pubblicata.
Prima di iniziare
Prima di iniziare a lavorare su una pull request (PR), ti chiediamo di aprire un'issue e discuterla con noi, così sappiamo su cosa stai lavorando e possiamo concordare l'approccio da adottare. Questo ti evita di dedicare tempo a una funzionalità che potrebbe non allinearsi con gli obiettivi del progetto. Nella tua PR farai quindi riferimento al numero dell'issue per collegare la nostra discussione.
Stile e linting
È importante che le tue modifiche producano commit puliti che possano essere revisionati rapidamente e senza distrazioni causate da diff spuri. Il progetto utilizza i seguenti strumenti di stile e linting:
| Linguaggio | Strumento | Note |
|---|---|---|
| Python | ruff | Linting e formattazione del codice |
| Python | mypy | Type checking |
Utilizziamo anche un file .editorconfig che configura gli editor compatibili per comportarsi in modo coerente per operazioni come la rimozione degli spazi finali o l'applicazione degli stili di indentazione.
Commit verificati
Per garantire l'integrità del nostro progetto, richiediamo commit verificati crittograficamente firmati. Segui le istruzioni su GitHub per utilizzare keypair gpg, ssh o s/mime.
Developer Certificate of Origin
Per garantire l'integrità legale del nostro progetto, richiediamo a tutti i contributori di firmare i propri commit, accettando così il Developer Certificate of Origin. Questo certifica che hai il diritto di inviare il codice sotto la licenza del progetto.
Aggiungi una riga Signed-off-by a ogni commit usando il flag -s:
git commit -s -m "<tipo>: <sommario> (#<numero issue>)"
Uso dell'Intelligenza Artificiale Generativa
La programmazione assistita da AI può essere utile, ma l'inclusione acritica di codice generato da AI può causare danni. Firmando i commit, attesti di aver scritto tutto il codice tu stesso o di aver revisionato e compreso appieno qualsiasi codice generato.
I contributi di codice che contengono codice generato da AI che non sei in grado di spiegarci completamente verranno rifiutati.
Standard per i messaggi di commit
Seguiamo la specifica Conventional Commits. Ogni messaggio di commit deve seguire questa struttura:
<tipo>: <descrizione sommaria> (#<numero issue>)
Signed-off-by: ...
| Tipo | Descrizione |
|---|---|
feat | Implementa una nuova funzionalità |
fix | Corregge un bug |
perf | Migliora le prestazioni |
refactor | Migliora il codice senza cambiarne il comportamento |
build | Modifica il sistema di build o CI |
docs | Aggiunge o migliora la documentazione |
style | Apporta solo modifiche stilistiche (es. whitespace) |
test | Aggiunge o migliora i test |
chore | Aggiorna il processo di build, prepara release, ecc. |