Lezione 24 di 35

Git 24

🔀 Git & GitHub · Modulo 4 · Lezione 24

Template per Issue e PR 📋

Standardizzare la comunicazione · Issue forms con YAML · PR template · Automatizzare le convenzioni

⏱️ Durata stimata: 60–75 min 📊 Livello: Intermedio-Avanzato (Modulo 4) 🔧 Strumenti: Terminale · Editor di testo · GitHub 📋 Prerequisiti: Lezioni 16–17 (issue e PR)

📋 Un bug report senza passi per riprodurre è inutile. Una PR senza descrizione è un mistero. Nella Lezione 16 hai visto i template Markdown base per le issue. In questa lezione vai oltre: crei issue forms (moduli interattivi con campi strutturati) e PR template (che si pre-compilano quando qualcuno apre una PR). Il risultato: tutti nel team comunicano con lo stesso formato, niente informazioni mancanti, niente tempo perso a chiedere dettagli.

🎯 Obiettivi della lezione

Capire la differenza tra template Markdown e issue forms YAML
Creare issue forms con campi strutturati (dropdown, textarea, checkbox)
Creare un PR template che si auto-compila in ogni nuova PR
Configurare il chooser che appare quando si apre una nuova issue
Organizzare la cartella .github del repository

📖 1. Teoria

1.1 — Template Markdown vs Issue Forms YAML

Nella Lezione 16 hai creato template in Markdown (.md). Funzionano, ma hanno un limite: l’utente vede un blocco di testo precompilato e deve cancellare i placeholder per scrivere le sue risposte. Con le issue forms (.yml), l’utente vede un modulo strutturato con campi veri — dropdown, textarea, checkbox — molto più guidato.

Template Markdown (.md)

L’utente vede un editor di testo con il template precompilato. Deve cancellare i placeholder e scrivere al loro posto. Nessuna validazione — può lasciare campi vuoti o cancellare sezioni intere.

Pro: semplice da creare. Contro: nessun controllo sulla compilazione.

Issue Form YAML (.yml) ⭐

L’utente vede un modulo con campi: textarea, dropdown, checkbox, input. I campi possono essere obbligatori — l’issue non si può aprire se sono vuoti. Molto più guidato e professionale.

Pro: strutturato, con validazione. Contro: sintassi YAML da imparare.

1.2 — La struttura della cartella .github

Tutti i template vivono nella cartella .github alla radice del repository. Ecco la struttura completa:

  📁 .github/

  ├── 📁 ISSUE_TEMPLATE/

  │   ├── bug_report.yml          # Issue form per bug

  │   ├── feature_request.yml     # Issue form per feature

  │   └── config.yml              # Configurazione del chooser

  └── PULL_REQUEST_TEMPLATE.md  # Template per le PR

1.3 — Issue Forms: i campi disponibili

Tipo di campo	YAML `type`	Cosa vede l’utente	Quando usarlo
Markdown	markdown	Testo informativo (non editabile)	Istruzioni, avvisi, separatori
Textarea	textarea	Box di testo grande (multi-riga)	Descrizioni, passi per riprodurre, codice
Input	input	Campo di testo singola riga	Versione, URL, nome del browser
Dropdown	dropdown	Menu a tendina con opzioni predefinite	Priorità, tipo di bug, browser, sistema operativo
Checkboxes	checkboxes	Lista di checkbox spuntabili	Conferme (“ho cercato issue simili”), checklist

1.4 — Issue Form: Bug Report completo

  # File: .github/ISSUE_TEMPLATE/bug_report.yml

  name: Bug Report

  description: Segnala un bug nel progetto

  title: “[Bug]: “

  labels: [“bug”]

  assignees: []

  body:

    – type: markdown

      attributes:

        value: |

          Grazie per la segnalazione! Compila tutti i campi per aiutarci a risolvere il bug.

    – type: textarea

      id: description

      attributes:

        label: Descrizione del bug

        description: Descrivi chiaramente cosa non funziona.

        placeholder: Quando clicco sul pulsante Invia, non succede nulla…

      validations:

        required: true

    – type: textarea

      id: steps

      attributes:

        label: Passi per riprodurre

        description: Elenca i passi per far comparire il bug.

        placeholder: |

          1. Apri la pagina contatti

          2. Lascia tutti i campi vuoti

          3. Clicca “Invia”

      validations:

        required: true

    – type: textarea

      id: expected

      attributes:

        label: Risultato atteso

        description: Cosa dovrebbe succedere?

      validations:

        required: true

    – type: textarea

      id: actual

      attributes:

        label: Risultato attuale

        description: Cosa succede invece?

      validations:

        required: true

    – type: dropdown

      id: browser

      attributes:

        label: Browser

        description: Su quale browser succede?

        options:

          – Chrome

          – Firefox

          – Safari

          – Edge

          – Altro

      validations:

        required: true

    – type: textarea

      id: screenshot

      attributes:

        label: Screenshot

        description: Se possibile, allega uno screenshot. Trascina l’immagine qui.

      validations:

        required: false

    – type: checkboxes

      id: checklist

      attributes:

        label: Conferme

        options:

          – label: Ho cercato issue simili e non ne ho trovate

            required: true

          – label: Ho testato con l’ultima versione del progetto

            required: true

📌 YAML è sensibile all’indentazione! Usa sempre 2 spazi (non tab) per indentare. Un’indentazione sbagliata rompe il file e il template non funziona. Se non sei sicuro, usa un validatore YAML online prima di committare.

1.5 — Issue Form: Feature Request

  # File: .github/ISSUE_TEMPLATE/feature_request.yml

  name: Feature Request

  description: Proponi una nuova funzionalità

  title: “[Feature]: “

  labels: [“enhancement”]

  body:

    – type: textarea

      id: description

      attributes:

        label: Descrizione della funzionalità

        description: Cosa vorresti aggiungere al progetto?

      validations:

        required: true

    – type: textarea

      id: motivation

      attributes:

        label: Perché è utile

        description: Quale problema risolve? Che valore aggiunge?

      validations:

        required: true

    – type: dropdown

      id: priority

      attributes:

        label: Priorità suggerita

        options:

          – 🔴 Alta — essenziale per la consegna

          – 🟡 Media — importante ma non bloccante

          – 🟢 Bassa — nice to have

      validations:

        required: true

    – type: textarea

      id: implementation

      attributes:

        label: Proposta di implementazione (opzionale)

        description: Se hai idee su come realizzarla, descrivile qui.

      validations:

        required: false

1.6 — Il config.yml: configurare il chooser

Il file config.yml nella cartella ISSUE_TEMPLATE configura il menu che appare quando qualcuno clicca “New issue”. Puoi aggiungere link esterni (es. alle Discussions) e disabilitare le issue senza template.

  # File: .github/ISSUE_TEMPLATE/config.yml

  blank_issues_enabled: false  # Impedisce issue senza template

  contact_links:

    – name: 💬 Domande e discussioni

      url: https://github.com/tuousername/progetto/discussions/new

      about: Hai una domanda? Usa le Discussions invece di aprire un’issue.

    – name: 📖 Documentazione

      url: https://github.com/tuousername/progetto/wiki

      about: Consulta la Wiki prima di aprire un’issue.

Cosa vede l’utente quando clicca “New issue”

🐛 Bug Report

Segnala un bug nel progetto

Get started

✨ Feature Request

Proponi una nuova funzionalità

Get started

💬 Domande e discussioni

Hai una domanda? Usa le Discussions.

Open ↗

L’utente sceglie il tipo giusto. Niente issue vuote o generiche.

1.7 — PR Template

Il PR template è un file Markdown che viene automaticamente inserito nella descrizione di ogni nuova Pull Request. Si crea come .github/PULL_REQUEST_TEMPLATE.md.

  # File: .github/PULL_REQUEST_TEMPLATE.md

  ## Cosa

  <!– Descrivi brevemente cosa fa questa PR –>

  ## Perché

  <!– Quale problema risolve? Collega l’issue: Closes #N –>

  ## Come testare

  <!– Passi per verificare che funziona –>

  1. 

  2. 

  3. 

  ## Screenshot

  <!– Se il cambiamento è visuale, allega screenshot –>

  ## Checklist

  – [ ] Ho testato le modifiche in locale

  – [ ] Il codice segue le convenzioni del progetto

  – [ ] Ho aggiornato la documentazione (se necessario)

  – [ ] Non ci sono console.log o codice di debug

📌 I commenti HTML  sono invisibili nel render. GitHub li nasconde nella PR pubblicata — l’autore li vede nell’editor come promemoria di cosa scrivere, ma il lettore della PR vede solo il testo reale. È un trucco elegante per dare istruzioni senza inquinare la descrizione.

💻 2. Esempi guidati

Esempio A — Setup completo della cartella .github

  # Crea la struttura

  $ mkdir -p .github/ISSUE_TEMPLATE

  # Crea i file (con il tuo editor preferito, oppure con cat)

  # 1. Bug report form → .github/ISSUE_TEMPLATE/bug_report.yml

  # 2. Feature request form → .github/ISSUE_TEMPLATE/feature_request.yml

  # 3. Config → .github/ISSUE_TEMPLATE/config.yml

  # 4. PR template → .github/PULL_REQUEST_TEMPLATE.md

  # Verifica la struttura

  $ find .github -type f

  .github/ISSUE_TEMPLATE/bug_report.yml

  .github/ISSUE_TEMPLATE/feature_request.yml

  .github/ISSUE_TEMPLATE/config.yml

  .github/PULL_REQUEST_TEMPLATE.md

  # Committa e pusha

  $ git add .github/

  $ git commit -m “Aggiunti template per issue (YAML forms) e PR”

  $ git push

Esempio B — Testare i template

Issue

Vai su GitHub → Issues → “New issue”. Vedi il chooser con Bug Report e Feature Request? Clicca “Bug Report” — vedi il modulo con i campi? Prova a inviare senza compilare un campo obbligatorio: GitHub blocca con un errore.

Crea un branch, fai un commit, pusha, apri una PR su GitHub. La descrizione è pre-compilata con il template? Vedi le sezioni “Cosa”, “Perché”, “Come testare” e la checklist?

🏋️ 3. Esercizi

🟢 Esercizio 1 — PR template (Facile)

a) Crea il file .github/PULL_REQUEST_TEMPLATE.md con le sezioni: Cosa, Perché, Come testare, Checklist.
b) Committa e pusha.
c) Crea un branch con una piccola modifica, pusha, apri una PR.
d) La descrizione è pre-compilata con il template? Compila le sezioni e crea la PR.
e) Le checkbox nella checklist sono cliccabili nella PR pubblicata?

🔵 Esercizio 2 — Issue form Bug Report (Medio)

a) Crea il file .github/ISSUE_TEMPLATE/bug_report.yml usando l’esempio della sezione 1.4.
b) Committa e pusha.
c) Su GitHub, clicca Issues → New issue. Vedi il modulo “Bug Report”?
d) Prova a inviare senza compilare un campo obbligatorio. GitHub blocca?
e) Compila tutti i campi e invia. L’issue creata è ben formattata?
f) Verifica che il label “bug” sia stato assegnato automaticamente.

🟠 Esercizio 3 — config.yml e chooser completo (Medio)

a) Crea anche il file feature_request.yml (sezione 1.5).
b) Crea il file config.yml (sezione 1.6) con blank_issues_enabled: false e un link alle Discussions.
c) Committa e pusha.
d) Su GitHub, clicca “New issue”. Vedi il chooser con Bug Report, Feature Request e il link alle Discussions?
e) Prova ad aprire un’issue vuota (senza template). È possibile? (Non deve esserlo — blank_issues_enabled: false.)

🟣 Esercizio 4 — Template personalizzato per il tuo progetto (Difficile)

Crea un set completo di template personalizzati per il tuo progetto scolastico:

a) Bug Report (.yml): adatta i campi al tuo progetto. Se è un sito web, aggiungi dropdown per browser e dispositivo. Se è un’app Python, aggiungi un campo per la versione Python.
b) Feature Request (.yml): aggiungi un dropdown “Area del progetto” con le sezioni specifiche del tuo progetto (es. Frontend, Backend, Database, UI/UX).
c) Compito scolastico (.yml): crea un terzo template con campi: “Descrizione del compito”, “Requisiti” (checklist), “Scadenza” (input), “Note per il prof” (textarea opzionale).
d) config.yml: disabilita le issue vuote, aggiungi link a Discussions e Wiki.
e) PR template: personalizza le sezioni e la checklist per il tuo progetto.
f) Committa tutto, pusha, e testa ogni template aprendo un’issue e una PR di prova.

❓ 4. Quiz di verifica

1. Qual è la differenza tra un template .md e un issue form .yml?

Mostra risposta

Il template .md (Markdown) mostra un editor di testo con il template precompilato — l’utente deve cancellare i placeholder e scrivere al loro posto. Non c’è validazione: può lasciare campi vuoti o cancellare sezioni intere. L’issue form .yml (YAML) mostra un modulo strutturato con campi veri: textarea, dropdown, input, checkbox. I campi possono essere obbligatori — GitHub impedisce l’invio se mancano. È molto più guidato e produce issue più uniformi e complete.

2. Cosa fa blank_issues_enabled: false nel config.yml?

Mostra risposta

Impedisce la creazione di issue vuote (senza template). Quando qualcuno clicca “New issue”, deve scegliere uno dei template disponibili — non può aprire un’issue generica con descrizione libera. Questo garantisce che ogni issue segua un formato standard con le informazioni necessarie. Senza questa opzione, il chooser mostra anche un link “Open a blank issue” che bypassa tutti i template.

3. Dove deve trovarsi il PR template nel repository?

Mostra risposta

In .github/PULL_REQUEST_TEMPLATE.md. Il file deve avere esattamente questo nome e posizione — GitHub lo riconosce automaticamente e inserisce il suo contenuto nella descrizione di ogni nuova Pull Request. A differenza dei template per le issue (dove puoi avere più file per diversi tipi), c’è un solo PR template per repository. Il contenuto è Markdown e può includere sezioni, checklist e commenti HTML invisibili che guidano l’autore.

4. A cosa servono i commenti HTML  nel PR template?

Mostra risposta

Servono come istruzioni invisibili per l’autore della PR. Nell’editor, l’autore vede i commenti e sa cosa scrivere in ogni sezione. Nella PR pubblicata, i commenti sono nascosti — il lettore vede solo il testo reale scritto dall’autore. È un modo elegante per guidare la compilazione senza inquinare la descrizione finale. Esempio:  spiega cosa scrivere nella sezione “Cosa”.

5. Quali tipi di campi sono disponibili nelle issue forms YAML?

Mostra risposta

Cinque tipi: markdown (testo informativo non editabile, per istruzioni), textarea (box di testo multi-riga, per descrizioni e codice), input (campo singola riga, per versioni e URL), dropdown (menu a tendina con opzioni predefinite, per categorie e priorità), e checkboxes (lista di checkbox, per conferme e checklist). Tutti i campi tranne markdown possono avere validations: required: true per renderli obbligatori.

6. Il tuo issue form YAML non funziona su GitHub. Qual è la causa più probabile?

Mostra risposta

L’indentazione YAML sbagliata. YAML è estremamente sensibile all’indentazione — usa spazi (non tab) e ogni livello deve avere esattamente 2 spazi in più del precedente. Un singolo spazio in più o in meno rompe l’intero file. Altre cause comuni: errori di sintassi (virgolette mancanti, due punti dimenticati), campi con nomi sbagliati (attribute invece di attributes), o il file non è nella cartella giusta (.github/ISSUE_TEMPLATE/). Per debug: usa un validatore YAML online, copia il contenuto del file e verifica che sia valido prima di committare.

📚 Riepilogo della lezione

Cosa hai imparato oggi:

Issue forms (.yml) ⭐: moduli strutturati con textarea, input, dropdown, checkbox — con validazione
Template .md = testo precompilato. Forms .yml = campi veri con controllo
Struttura: .github/ISSUE_TEMPLATE/ per issue, .github/PULL_REQUEST_TEMPLATE.md per PR
config.yml: blank_issues_enabled: false + link a Discussions/Wiki nel chooser
PR template: si auto-compila in ogni PR — sezioni Cosa/Perché/Come testare/Checklist
Commenti HTML  = istruzioni invisibili nel render
YAML: attenzione all’indentazione — 2 spazi, mai tab

🎉 Congratulazioni! Hai completato il Modulo 4 — Collaborazione avanzata. Sai fare fork, proteggere branch, gestire progetti con Kanban, creare milestone e release, usare Discussions e Wiki, e standardizzare la comunicazione con template professionali. Dal prossimo modulo si entra nel mondo dell’automazione: GitHub Actions e CI/CD.

Prossima lezione →

Lezione 25 — Introduzione a GitHub Actions
Cos’è la CI/CD. Workflow automatici. Il tuo primo Action.
Automatizzare test, build e deploy.

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