Lezione 16 di 35

Git 16

🔀 Git & GitHub · Modulo 3 · Lezione 16

GitHub Issues 🎯

Creare e gestire issue · Etichette e assegnazioni · Referenziare nei commit · Template per issue

⏱️ Durata stimata: 60–75 min 📊 Livello: Intermedio (Modulo 3) 🔧 Strumenti: Browser (github.com) · Terminale per i commit 📋 Prerequisiti: Lezione 14–15 (repository su GitHub con push funzionante)

🎯 Le issue sono la “lista delle cose da fare” del progetto. Ogni bug da correggere, ogni funzionalità da aggiungere, ogni idea da discutere diventa un’issue — numerata, tracciabile, assegnabile. In un progetto scolastico le issue diventano il modo per dividere il lavoro: “Marco, prendi l’issue #3 (navbar). Giulia, prendi la #5 (contatti).” Tutto è tracciato e nulla si perde.

🎯 Obiettivi della lezione

Capire cos’è un’issue e come si usa nella gestione di un progetto
Creare un’issue con titolo, descrizione e checklist
Usare le etichette (label) per categorizzare le issue
Assegnare le issue ai membri del team
Referenziare le issue nei commit per collegare codice e task
Chiudere automaticamente le issue tramite commit e pull request
Creare template per issue ripetitive

📖 1. Teoria

1.1 — Cos’è un’issue

Un’issue è una scheda di lavoro nel tuo repository GitHub. Può rappresentare un bug, una feature da implementare, una domanda, un miglioramento o qualsiasi attività legata al progetto. Ogni issue ha un numero univoco (es. #1, #2, #3) che la identifica per sempre nel repository.

🐛

Bug report

“Il totale del carrello non si aggiorna quando rimuovo un prodotto”

✨

Feature request

“Aggiungere la modalità scura al sito”

💬

Discussione / domanda

“Quale framework CSS usiamo per il progetto?”

1.2 — Anatomia di un’issue

OBBLIGATORIO

Titolo

Breve e descrittivo. Es: “Bug: il form di contatto non invia l’email”

Sempre

CONSIGLIATO

Descrizione

Dettagli: cosa succede, cosa dovrebbe succedere, passi per riprodurre. Supporta Markdown.

Quasi sempre

OPZIONALE

Etichette (Labels)

Categorie colorate: bug, enhancement, documentation, help wanted.

Progetti medi+

OPZIONALE

Assignee

Chi è responsabile di questa issue. Puoi assegnare te stesso o un compagno.

Progetti di gruppo

OPZIONALE

Milestone

A quale obiettivo o versione appartiene questa issue (es: “v1.0”, “Consegna marzo”).

Progetti con rilasci

1.3 — Creare un’issue

PASSO 1

Vai al tuo repository su GitHub → clicca la tab “Issues” → “New issue”.

PASSO 2

Scrivi un titolo chiaro e breve. Es: “Aggiungere validazione al form di contatto”.

PASSO 3

Nella descrizione aggiungi i dettagli. Usa Markdown per formattare: checklist con - [ ], blocchi di codice, screenshot.

PASSO 4

Nella sidebar destra: assegna un label (etichetta), un assignee (responsabile), e opzionalmente una milestone.

PASSO 5

Clicca “Submit new issue”. L’issue riceve un numero (es. #1) e appare nella lista.

1.4 — Scrivere una buona descrizione: il potere della checklist

Le checklist in Markdown (scritte con - [ ]) diventano checkbox cliccabili su GitHub — perfette per spezzare un’issue in sotto-task:

Scrivi (Markdown)

        ## Cosa serve fare

        – [ ] Validare il campo email

        – [ ] Validare il campo nome (min 2 caratteri)

        – [ ] Mostrare errori sotto i campi

        – [ ] Disabilitare il pulsante se il form non è valido

        ## Come riprodurre il bug

        1. Apri la pagina contatti

        2. Lascia il campo email vuoto

        3. Clicca “Invia”

        4. **Risultato attuale:** il form si invia

        5. **Risultato atteso:** errore “Email obbligatoria”

Vedi su GitHub (renderizzato)

Cosa serve fare

☐ Validare il campo email
☐ Validare il campo nome (min 2 caratteri)
☐ Mostrare errori sotto i campi
☐ Disabilitare il pulsante se il form non è valido

Come riprodurre il bug

1. Apri la pagina contatti
2. Lascia il campo email vuoto
3. Clicca “Invia”
4. Risultato attuale: il form si invia
5. Risultato atteso: errore “Email obbligatoria”

📌 Le checkbox sono cliccabili! Puoi spuntarle direttamente su GitHub quando completi un sotto-task, senza dover modificare il testo. GitHub mostra anche un contatore di progresso (es. “2 of 4 tasks”) nella lista delle issue. È un modo semplice e potente di tracciare l’avanzamento.

1.5 — Etichette (Labels): categorizzare le issue

Le etichette sono tag colorati che categorizzano le issue. GitHub fornisce etichette predefinite — puoi usarle così come sono, modificarle o crearne di nuove.

Etichetta	Colore tipico	Quando usarla
bug	Rosso	Qualcosa non funziona come previsto
enhancement	Blu	Nuova funzionalità o miglioramento
good first issue	Verde	Issue semplice, ideale per chi è alle prime armi
help wanted	Verde acqua	Serve aiuto — invita i compagni a contribuire
documentation	Viola	Miglioramenti alla documentazione (README, wiki)
question	Giallo	Domanda o richiesta di chiarimento
priority: high	Rosso scuro	Da risolvere subito (etichetta personalizzata)

Puoi creare etichette personalizzate: vai su Issues → Labels → “New label”. Scegli nome, descrizione e colore. Per un progetto scolastico, potresti aggiungere etichette come compito, facile, difficile, bonus.

1.6 — Referenziare le issue nei commit

Ecco la parte potente: puoi collegare i commit alle issue semplicemente menzionando il numero dell’issue nel messaggio del commit. GitHub crea automaticamente un link tra i due.

  # Menzionare un’issue nel commit (crea un link)

  $ git commit -m “Aggiunta validazione email, ref #3”

  # Chiudere automaticamente un’issue con il commit

  $ git commit -m “Aggiunta validazione completa del form, closes #3”

  # Dopo il push, GitHub chiude l’issue #3 automaticamente!

  $ git push

Parola chiave nel commit	Effetto
#3	Crea un link all’issue #3 — ma non la chiude
ref #3	Stessa cosa: link senza chiusura (riferimento esplicito)
closes #3	Crea un link e chiude automaticamente l’issue #3 quando il commit arriva su main
fixes #3	Stessa cosa di closes (alternativa)
resolves #3	Stessa cosa di closes (alternativa)

La chiusura automatica funziona solo quando il commit arriva sul branch predefinito (main). Se il commit è su un feature branch, l’issue viene chiusa quando fai merge in main (o quando la PR viene integrata).

📌 Il workflow ideale: crea un’issue → crea un branch con un nome che la referenzia (es. fix/3-validazione-form) → lavora → nel commit finale scrivi closes #3 → fai merge in main → l’issue si chiude da sola. L’intera storia è tracciata: l’issue descrive il problema, il branch contiene il lavoro, il commit chiude il cerchio.

1.7 — Il ciclo di vita di un’issue

1. CREA

Qualcuno apre
l’issue su GitHub

2. ASSEGNA

Etichetta + assegna
a un membro

3. LAVORA

Branch + commit
con ref #N

4. REVIEW

PR con closes #N
code review

5. CHIUDI

Merge in main
issue chiusa

1.8 — Template per le issue

Se le tue issue seguono sempre lo stesso formato (es. bug report con “passi per riprodurre” e “risultato atteso”), puoi creare un template — un modello pre-compilato che appare quando qualcuno apre una nuova issue.

Come creare un template (modo semplice)

Nel tuo repository, crea la cartella .github/ISSUE_TEMPLATE/.

Crea un file Markdown per ogni tipo di template, es: bug_report.md, feature_request.md.

Committa e pusha. D’ora in poi, quando qualcuno clicca “New issue”, vedrà un menu con i template disponibili.

  # File: .github/ISSUE_TEMPLATE/bug_report.md

  —

  name: Bug Report

  about: Segnala un bug nel progetto

  title: “Bug: “

  labels: bug

  assignees: ”

  —

  ## Descrizione del bug

  Descrivi chiaramente cosa non funziona.

  ## Passi per riprodurre

  1. Vai a ‘…’

  2. Clicca su ‘…’

  3. Scorri fino a ‘…’

  4. Vedi l’errore

  ## Risultato atteso

  Cosa dovrebbe succedere.

  ## Risultato attuale

  Cosa succede invece.

  ## Screenshot

  Se possibile, aggiungi screenshot.

  # File: .github/ISSUE_TEMPLATE/feature_request.md

  —

  name: Feature Request

  about: Proponi una nuova funzionalità

  title: “Feature: “

  labels: enhancement

  assignees: ”

  —

  ## Descrizione

  Descrivi la funzionalità che vorresti aggiungere.

  ## Perché è utile

  Spiega il valore che porta al progetto.

  ## Proposta di implementazione

  Se hai idee su come implementarla, descrivile qui.

  ## Checklist

  – [ ] Task 1

  – [ ] Task 2

  – [ ] Test

💻 2. Esempi guidati

Esempio A — Creare 3 issue per un progetto scolastico

Scenario: progetto “Sito della classe”

bug Issue #1: Bug — il menu mobile non si chiude

Quando clicco un link nel menu hamburger su mobile, il menu resta aperto. Dovrebbe chiudersi automaticamente dopo la navigazione. Assegnata a: Marco.

enhancement Issue #2: Feature — aggiungere pagina “Chi siamo”

Creare una pagina con la presentazione di ogni membro della classe. Include: foto, nome, hobby. Assegnata a: Giulia.

documentation Issue #3: Docs — aggiornare README con istruzioni di sviluppo

Il README attuale non spiega come far partire il progetto in locale. Aggiungere sezione “Sviluppo locale” con i comandi. Assegnata a: Luca.

Esempio B — Collegare commit e issue

  # Marco lavora sull’issue #1 (bug menu mobile)

  $ git switch -c fix/1-menu-mobile

  # Primo commit — riferimento all’issue

  $ git commit -m “Aggiunto event listener per chiusura menu, ref #1”

  # Commit finale — chiude l’issue

  $ git commit -m “Fix completo del menu mobile, closes #1”

  $ git push -u origin fix/1-menu-mobile

  # Dopo il merge in main (tramite PR), l’issue #1 si chiude automaticamente.

  # Su GitHub, nell’issue #1 appare il link al commit e alla PR.

Esempio C — Aggiungere template per le issue

  # Crea la struttura per i template

  $ mkdir -p .github/ISSUE_TEMPLATE

  # Crea il template per bug report

  $ cat > .github/ISSUE_TEMPLATE/bug_report.md <<‘EOF’

  —

  name: Bug Report

  about: Segnala un bug

  title: “Bug: “

  labels: bug

  —

  ## Descrizione

  [Descrivi il bug]

  ## Passi per riprodurre

  1. …

  2. …

  ## Risultato atteso

  [Cosa dovrebbe succedere]

  ## Risultato attuale

  [Cosa succede invece]

  EOF

  $ git add .github/ && git commit -m “Aggiunti template per le issue”

  $ git push

  # Ora su GitHub: Issues → New issue → appare il menu con i template!

🏋️ 3. Esercizi

🟢 Esercizio 1 — Crea le tue prime issue (Facile)

a) Vai su uno dei tuoi repository su GitHub.
b) Crea 3 issue per miglioramenti che vorresti fare al progetto. Per ciascuna: titolo chiaro, descrizione con almeno 3 righe, un label appropriato.
c) Per almeno una issue, usa una checklist con - [ ].
d) Assegna almeno una issue a te stesso (Assignee).
e) Verifica nella tab Issues: le 3 issue sono lì, con i label colorati.

🔵 Esercizio 2 — Collegare commit e issue (Medio)

a) Scegli una delle issue create nell’Esercizio 1. Nota il numero (es. #2).
b) Crea un branch con il numero dell’issue nel nome: git switch -c feature/2-nome-funzione.
c) Fai almeno 2 commit. Nel primo, usa ref #2 nel messaggio. Nell’ultimo, usa closes #2.
d) Pusha il branch e fai merge in main (direttamente o tramite PR su GitHub).
e) Vai su GitHub: l’issue #2 è stata chiusa automaticamente? Nei commenti dell’issue appaiono i link ai commit?

🟠 Esercizio 3 — Etichette personalizzate (Medio)

a) Vai su Issues → Labels nel tuo repository.
b) Crea 4 etichette personalizzate per un progetto scolastico: priorità: alta (rosso), priorità: bassa (verde), frontend (blu), backend (arancione).
c) Crea 2 nuove issue e assegna almeno 2 etichette a ciascuna (una di tipo e una di priorità).
d) Filtra le issue per etichetta: nella tab Issues, clicca su un label per vedere solo le issue con quell’etichetta.

🟣 Esercizio 4 — Template per issue (Difficile)

a) Crea la cartella .github/ISSUE_TEMPLATE/ nel tuo repository.
b) Crea 2 template: bug_report.md e feature_request.md (usa gli esempi della sezione 1.8 come base).
c) Personalizza i template per il tuo progetto — aggiungi sezioni specifiche se serve.
d) Committa e pusha.
e) Vai su GitHub → Issues → New issue. Vedi il menu con i template?
f) Crea un’issue usando il template Bug Report. Le sezioni pre-compilate appaiono?
g) Sfida bonus: aggiungi un terzo template compito.md per le consegne scolastiche, con sezioni: “Descrizione compito”, “Requisiti”, “Scadenza”, “Checklist consegna”.

❓ 4. Quiz di verifica

1. Cosa sono le issue su GitHub e a cosa servono?

Mostra risposta

Le issue sono schede di lavoro associate a un repository. Servono a tracciare bug, feature da implementare, miglioramenti, domande e qualsiasi attività legata al progetto. Ogni issue ha un numero univoco, un titolo, una descrizione, e può avere etichette, assegnatari e milestone. Funzionano come una “lista delle cose da fare” del progetto, ma integrata con il codice — puoi collegare issue a commit, branch e pull request.

2. Qual è la differenza tra scrivere #3 e closes #3 nel messaggio di un commit?

Mostra risposta

#3 crea solo un link tra il commit e l’issue #3 — l’issue resta aperta. closes #3 (o fixes #3, resolves #3) crea il link E chiude automaticamente l’issue quando il commit arriva sul branch predefinito (main). Se il commit è su un feature branch, la chiusura avviene quando il branch viene integrato in main tramite merge o pull request.

3. A cosa servono le etichette (labels) sulle issue?

Mostra risposta

Le etichette sono tag colorati che categorizzano le issue. Servono a distinguere rapidamente i tipi di issue (bug, feature, documentazione), le priorità (alta, bassa), le aree del progetto (frontend, backend) o qualsiasi altra categorizzazione utile. Puoi filtrare la lista delle issue per etichetta — utile quando hai molte issue aperte e vuoi trovare rapidamente quelle di un certo tipo. GitHub fornisce etichette predefinite ma puoi crearne di personalizzate.

4. Cosa succede quando scrivi - [ ] Completare il test nella descrizione di un’issue?

Mostra risposta

GitHub renderizza questa riga come una checkbox cliccabile. Puoi spuntarla direttamente dall’interfaccia web quando il sotto-task è completato, senza dover modificare il testo dell’issue. Se ci sono più checkbox, GitHub mostra anche un contatore di progresso (es. “2 of 4 tasks”) nella lista delle issue, dando una visione immediata dell’avanzamento. La sintassi per una checkbox spuntata è - [x] Task completato.

5. Dove si mettono i template per le issue nel repository?

Mostra risposta

Nella cartella .github/ISSUE_TEMPLATE/ alla radice del repository. Ogni file .md in questa cartella diventa un template disponibile. Il file deve iniziare con un frontmatter YAML (tra ---) che specifica name (nome del template), about (descrizione), title (prefisso del titolo), e labels (etichette automatiche). Quando qualcuno clicca “New issue”, GitHub mostra un menu con tutti i template disponibili.

6. In un progetto di gruppo, quale workflow integra issue, branch e commit?

Mostra risposta

Il workflow ideale è: (1) crea un’issue che descrive il task, (2) crea un branch con il numero dell’issue nel nome (es. feature/5-pagina-contatti), (3) lavora e committa con riferimenti all’issue (es. ref #5), (4) nell’ultimo commit o nella PR, usa closes #5, (5) apri una Pull Request verso main, (6) dopo la review e il merge, l’issue si chiude automaticamente. Tutto è collegato: l’issue documenta il “perché”, il branch il “come”, i commit il “cosa”, e la PR la review. È il workflow standard di GitHub Flow applicato con le issue.

📚 Riepilogo della lezione

Cosa hai imparato oggi:

Le issue sono schede di lavoro: bug, feature, domande — numerate e tracciabili
Anatomia: titolo + descrizione + label + assignee (+ milestone opzionale)
- [ ] nelle issue crea checkbox cliccabili con contatore di progresso
Labels: tag colorati per categorizzare (bug, enhancement, documentation…)
Nei commit: #N = link · closes #N / fixes #N = chiude l’issue
Workflow: issue → branch feature/N-nome → commit con ref #N → closes #N → merge
Template: file .md in .github/ISSUE_TEMPLATE/ con frontmatter YAML

Prossima lezione →

Lezione 17 — Pull Request
Creare una PR, descriverla, richiedere review. Merge di una PR.
Differenza tra PR e merge locale. Il cuore della collaborazione su GitHub.

Corso Git & GitHub · Per studenti e insegnanti · Lezione 16 di 45