Skip to content

Commit 8d63d0c

Browse files
author
Enrico Pascatti
committed
ci: governance repo — CI, template, CONTRIBUTING, formattazione
- GitHub Actions CI: lint (ruff + black), test (pytest), security (pip-audit) - Template issue: bug report e feature request strutturati - Template PR: checklist con issue obbligatoria e disclosure AI - CONTRIBUTING: regola issue-prima-della-PR, policy AI, tempi di risposta - Formattazione black + fix ruff su main.py e utils.py
1 parent 52ba339 commit 8d63d0c

8 files changed

Lines changed: 901 additions & 501 deletions

File tree

‎.github/ISSUE_TEMPLATE/bug_report.yml‎

Lines changed: 69 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,69 @@
1+
name: "🐛 Bug Report"
2+
description: Segnala un problema o un comportamento inatteso
3+
title: "[Bug]: "
4+
labels: ["bug", "triage"]
5+
body:
6+
- type: markdown
7+
attributes:
8+
value: |
9+
Grazie per la segnalazione! Compila tutti i campi per aiutarci a riprodurre il problema.
10+
**NON includere mai credenziali, codici fiscali o dati personali.**
11+
12+
- type: textarea
13+
id: description
14+
attributes:
15+
label: Descrizione del problema
16+
description: Descrivi cosa è successo
17+
placeholder: "Quando faccio X, succede Y invece di Z..."
18+
validations:
19+
required: true
20+
21+
- type: textarea
22+
id: steps
23+
attributes:
24+
label: Passi per riprodurre
25+
description: Elenca i passi per riprodurre il problema
26+
placeholder: |
27+
1. Avvia il servizio con `uvicorn main:app`
28+
2. Invia una richiesta POST a /visura con ...
29+
3. Osserva l'errore ...
30+
validations:
31+
required: true
32+
33+
- type: textarea
34+
id: expected
35+
attributes:
36+
label: Comportamento atteso
37+
description: Cosa ti aspettavi che succedesse?
38+
validations:
39+
required: true
40+
41+
- type: textarea
42+
id: logs
43+
attributes:
44+
label: Log rilevanti
45+
description: Incolla eventuali log (rimuovi SEMPRE credenziali e dati personali!)
46+
render: shell
47+
48+
- type: dropdown
49+
id: environment
50+
attributes:
51+
label: Ambiente
52+
options:
53+
- Docker
54+
- Locale (venv)
55+
- Altro
56+
validations:
57+
required: true
58+
59+
- type: input
60+
id: python-version
61+
attributes:
62+
label: Versione Python
63+
placeholder: "3.11.x"
64+
65+
- type: input
66+
id: os
67+
attributes:
68+
label: Sistema operativo
69+
placeholder: "Ubuntu 22.04 / macOS 14 / ..."

‎.github/ISSUE_TEMPLATE/config.yml‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,8 @@
1+
blank_issues_enabled: false
2+
contact_links:
3+
- name: "🔒 Vulnerabilità di sicurezza"
4+
url: https://github.com/zornade/visura-api/security/advisories/new
5+
about: "NON aprire issue pubbliche per problemi di sicurezza. Usa il Security Advisory."
6+
- name: "💬 Domande e discussioni"
7+
url: https://github.com/zornade/visura-api/discussions
8+
about: "Per domande generali, usa le Discussions invece di aprire una issue."

‎.github/ISSUE_TEMPLATE/feature_request.yml‎

Lines changed: 40 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,40 @@
1+
name: "✨ Feature Request"
2+
description: Proponi una nuova funzionalità o un miglioramento
3+
title: "[Feature]: "
4+
labels: ["enhancement"]
5+
body:
6+
- type: markdown
7+
attributes:
8+
value: |
9+
Grazie per la proposta! Prima di aprire questa issue, verifica che non esista già una richiesta simile.
10+
11+
- type: textarea
12+
id: problem
13+
attributes:
14+
label: Problema o motivazione
15+
description: Quale problema risolve questa funzionalità? Oppure perché sarebbe utile?
16+
placeholder: "Mi trovo spesso a dover fare X manualmente, e sarebbe utile se..."
17+
validations:
18+
required: true
19+
20+
- type: textarea
21+
id: solution
22+
attributes:
23+
label: Soluzione proposta
24+
description: Descrivi la soluzione che immagini
25+
placeholder: "Un nuovo endpoint che fa Y, oppure un parametro Z in /visura..."
26+
validations:
27+
required: true
28+
29+
- type: textarea
30+
id: alternatives
31+
attributes:
32+
label: Alternative considerate
33+
description: Hai considerato altre soluzioni? Se sì, perché le hai scartate?
34+
35+
- type: checkboxes
36+
id: willingness
37+
attributes:
38+
label: Disponibilità a contribuire
39+
options:
40+
- label: Sono disponibile a implementare questa feature e aprire una PR

‎.github/pull_request_template.md‎

Lines changed: 43 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,43 @@
1+
## Issue collegata
2+
3+
<!-- OBBLIGATORIO: ogni PR deve essere collegata a una issue approvata. -->
4+
<!-- Se non esiste una issue, aprila prima di inviare la PR. -->
5+
Risolve #
6+
7+
## Descrizione
8+
9+
<!-- Descrivi brevemente cosa fa questa PR e perché. -->
10+
11+
## Tipo di modifica
12+
13+
- [ ] Bug fix (corregge un problema senza rompere funzionalità esistenti)
14+
- [ ] Nuova feature (aggiunge funzionalità senza rompere quelle esistenti)
15+
- [ ] Breaking change (modifica che potrebbe rompere funzionalità esistenti)
16+
- [ ] Documentazione
17+
- [ ] Refactoring (nessun cambio funzionale)
18+
19+
## Checklist
20+
21+
- [ ] Ho letto [CONTRIBUTING.md](../CONTRIBUTING.md)
22+
- [ ] La mia PR è basata sull'ultimo `main` (ho fatto rebase)
23+
- [ ] Ho testato le modifiche localmente
24+
- [ ] Il codice passa `ruff check .` e `black --check .`
25+
- [ ] Ho aggiornato il CHANGELOG.md (se applicabile)
26+
- [ ] Ho aggiunto/aggiornato i test (se applicabile)
27+
- [ ] Non ho committato credenziali, dati personali o file `.env`
28+
29+
## Uso di strumenti AI
30+
31+
<!-- Trasparenza: dichiara se hai usato strumenti AI (Copilot, ChatGPT, ecc.) -->
32+
- [ ] Non ho usato strumenti AI per questa PR
33+
- [ ] Ho usato strumenti AI come supporto (specificare quali e come sotto)
34+
35+
<!-- Se hai usato AI, descrivi brevemente come: -->
36+
37+
## Screenshot / Log
38+
39+
<!-- Se utile, aggiungi screenshot o log (SENZA dati personali). -->
40+
41+
## Note per il reviewer
42+
43+
<!-- Qualcosa di specifico su cui vorresti feedback? -->

‎.github/workflows/ci.yml‎

Lines changed: 79 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,79 @@
1+
name: CI
2+
3+
on:
4+
push:
5+
branches: [main]
6+
pull_request:
7+
branches: [main]
8+
9+
permissions:
10+
contents: read
11+
12+
jobs:
13+
lint:
14+
name: Lint & Format Check
15+
runs-on: ubuntu-latest
16+
steps:
17+
- uses: actions/checkout@v4
18+
19+
- name: Set up Python
20+
uses: actions/setup-python@v5
21+
with:
22+
python-version: "3.11"
23+
24+
- name: Install dependencies
25+
run: |
26+
python -m pip install --upgrade pip
27+
pip install ruff black
28+
29+
- name: Check formatting with Black
30+
run: black --check --diff .
31+
32+
- name: Lint with Ruff
33+
run: ruff check .
34+
35+
test:
36+
name: Tests
37+
runs-on: ubuntu-latest
38+
needs: lint
39+
steps:
40+
- uses: actions/checkout@v4
41+
42+
- name: Set up Python
43+
uses: actions/setup-python@v5
44+
with:
45+
python-version: "3.11"
46+
47+
- name: Install dependencies
48+
run: |
49+
python -m pip install --upgrade pip
50+
pip install -r requirements.txt
51+
pip install pytest pytest-cov pytest-asyncio
52+
53+
- name: Install Playwright browsers
54+
run: playwright install chromium --with-deps
55+
56+
- name: Run tests
57+
run: python -m pytest -v --tb=short || [ $? -eq 5 ]
58+
env:
59+
ADE_USERNAME: test
60+
ADE_PASSWORD: test
61+
62+
security:
63+
name: Dependency Audit
64+
runs-on: ubuntu-latest
65+
steps:
66+
- uses: actions/checkout@v4
67+
68+
- name: Set up Python
69+
uses: actions/setup-python@v5
70+
with:
71+
python-version: "3.11"
72+
73+
- name: Install dependencies
74+
run: |
75+
python -m pip install --upgrade pip
76+
pip install pip-audit
77+
78+
- name: Audit dependencies
79+
run: pip-audit -r requirements.txt

‎CONTRIBUTING.md‎

Lines changed: 47 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -2,23 +2,49 @@
22

33
Grazie per il tuo interesse nel contribuire a Visura API! Questo documento fornisce le linee guida per partecipare al progetto.
44

5+
> **Regola fondamentale**: prima di scrivere codice, **apri sempre una issue** per discutere la modifica. Le PR senza issue collegata e approvata non verranno revisionate. Questo vale per feature, refactoring e fix non banali.
6+
7+
## Tempi di risposta
8+
9+
Questo progetto è mantenuto nel tempo libero. Ecco cosa aspettarsi:
10+
11+
- **Issue**: risposta entro 7 giorni
12+
- **PR con issue approvata**: prima review entro 14 giorni
13+
- **PR senza issue**: chiusa con richiesta di aprire prima una issue
14+
15+
Se non ricevi risposta entro questi tempi, sentiti libero di fare un ping gentile nel thread.
16+
517
## Codice di condotta
618

719
Partecipando a questo progetto accetti di rispettare il nostro [Codice di Condotta](CODE_OF_CONDUCT.md).
820

21+
## Policy sull'uso di strumenti AI
22+
23+
L'uso di strumenti AI (GitHub Copilot, ChatGPT, Claude, ecc.) come **supporto** è benvenuto, ma con regole chiare:
24+
25+
- **Dichiaralo**: nel template della PR c'è una sezione apposita. Sii trasparente su cosa è stato generato da AI.
26+
- **Comprendi il codice**: devi essere in grado di spiegare ogni riga della tua PR. Se il reviewer ti chiede "perché hai fatto X?" e la risposta è "l'ha scritto l'AI", la PR verrà rifiutata.
27+
- **Testa tutto**: il codice generato da AI deve essere testato localmente end-to-end, esattamente come il codice scritto a mano.
28+
- **No bulk PR**: le PR che riformattano massivamente il codice o aggiungono centinaia di righe non richieste non verranno revisionate. Mantieni le PR piccole e focalizzate.
29+
30+
Le PR palesemente generate da AI senza comprensione del progetto (selettori sbagliati, flussi non testati, dipendenze inventate) verranno chiuse senza review.
31+
932
## Come segnalare un problema
1033

1134
1. Controlla prima le [issue esistenti](https://github.com/zornade/visura-api/issues) per assicurarti che il problema non sia già stato segnalato
1235
2. Se è un problema di sicurezza, **NON** aprire una issue pubblica — segui le istruzioni in [SECURITY.md](SECURITY.md)
13-
3. Apri una nuova issue usando il template appropriato, fornendo:
14-
- Descrizione chiara del problema
15-
- Passi per riprodurlo
16-
- Comportamento atteso vs comportamento osservato
17-
- Versione di Python e del sistema operativo
18-
- Log pertinenti (rimuovi sempre le credenziali!)
36+
3. Apri una nuova issue usando il template appropriato (Bug Report o Feature Request)
1937

2038
## Come proporre modifiche
2139

40+
### Regola: Issue prima, PR dopo
41+
42+
1. **Apri una issue** descrivendo cosa vuoi fare e perché
43+
2. **Attendi il via libera** del maintainer (etichetta `approved` o commento esplicito)
44+
3. **Solo dopo**, crea il fork e scrivi il codice
45+
46+
Questo evita di sprecare il tuo tempo su modifiche che non verranno accettate e permette di allinearsi sull'architettura prima di scrivere codice.
47+
2248
### Preparare l'ambiente di sviluppo
2349

2450
```bash
@@ -52,16 +78,28 @@ cp .env.example .env
5278
```
5379
3. **Scrivi il codice** seguendo le convenzioni del progetto
5480
4. **Aggiungi test** per le modifiche, se applicabile
55-
5. **Esegui i test** per verificare che nulla sia rotto:
81+
5. **Verifica linting e formattazione** prima del commit:
82+
```bash
83+
black --check .
84+
ruff check .
85+
```
86+
6. **Esegui i test** per verificare che nulla sia rotto:
5687
```bash
5788
python -m pytest test_*.py -v
5889
```
59-
6. **Fai commit** con messaggi chiari in italiano:
90+
7. **Fai rebase su main** prima di aprire la PR:
91+
```bash
92+
git fetch upstream
93+
git rebase upstream/main
94+
```
95+
8. **Fai commit** con messaggi chiari in italiano:
6096
```bash
6197
git commit -m "fix: corretto errore nella selezione della provincia"
6298
git commit -m "feat: aggiunto supporto per ricerca per codice fiscale"
6399
```
64-
7. **Apri una Pull Request** verso il branch `main`
100+
9. **Apri una Pull Request** verso il branch `main`, compilando il template e collegando la issue
101+
102+
> ⚡ La CI eseguirà automaticamente linting (ruff + black), test e un audit di sicurezza sulle dipendenze. Assicurati che passi tutto prima di chiedere la review.
65103
66104
### Convenzioni per i messaggi di commit
67105

0 commit comments

Comments
 (0)