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>)"
REUSE 3.3 — Header di Copyright
Questo progetto applica la conformità REUSE 3.3 tramite un hook pre-commit. Ogni file sorgente deve avere un header di copyright SPDX.
File con un solo autore (default)
# SPDX-FileCopyrightText: 2026 PythonWoods <[email protected]>
# SPDX-License-Identifier: Apache-2.0
File con più autori — aggiungi, non sovrascrivere
Se contribuisci a un file che ha già un header di copyright, aggiungi la tua
riga SPDX-FileCopyrightText su una nuova riga immediatamente sotto quella
esistente. Non sostituire né rimuovere la riga dell'autore originale:
# SPDX-FileCopyrightText: 2026 PythonWoods <[email protected]>
# SPDX-FileCopyrightText: 2026 Il Tuo Nome <[email protected]>
# SPDX-License-Identifier: Apache-2.0
La riga SPDX-License-Identifier va per ultima e appare una sola volta per file.
Il normalizzatore di Zenzic salta le righe SPDX-FileCopyrightText durante i
controlli del conteggio parole (Z502) — sono metadati, non prosa. Lo Shield (Z201)
non si attiva nemmeno su queste righe, perché gli indirizzi email di copyright sono
strutturalmente diversi dai pattern di credenziali.
File MDX / JSX
Usa la sintassi dei commenti MDX:
{/* SPDX-FileCopyrightText: 2026 PythonWoods <[email protected]> */}
{/* SPDX-FileCopyrightText: 2026 Il Tuo Nome <[email protected]> */}
{/* SPDX-License-Identifier: Apache-2.0 */}
File che non possono avere header inline
Per file binari, asset generati o formati senza sintassi per commenti, aggiungi una
voce in REUSE.toml nella root del repository invece di header inline.
L'hook pre-commit valida sia gli header inline che le voci in REUSE.toml.
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. |