Lezione 23 di 35

Git 23

🔀 Git & GitHub · Modulo 4 · Lezione 23

Discussions e Wiki 💬

Spazi di discussione · Documentazione collaborativa · Wiki del progetto · Discussions vs Issues

⏱️ Durata stimata: 45–60 min 📊 Livello: Intermedio (Modulo 4) 🔧 Strumenti: Browser (github.com) 📋 Prerequisiti: Lezione 16 (issue)

💬 Non tutto è un bug o una feature. A volte serve discutere un’idea, chiedere aiuto, proporre un cambiamento di direzione, o documentare come funziona un componente. Le issue non sono il posto giusto per questo — sono pensate per task concreti da chiudere. GitHub offre due strumenti dedicati: Discussions per le conversazioni e Wiki per la documentazione. In questa lezione impari quando usare ciascuno.

🎯 Obiettivi della lezione

  • Capire quando usare Discussions, Issues e Wiki
  • Attivare e configurare GitHub Discussions
  • Creare una discussione con categorie
  • Attivare e usare la Wiki del repository
  • Scrivere pagine Wiki in Markdown
  • Scegliere lo strumento giusto per ogni situazione

📖 1. Teoria

1.1 — Il problema: non tutto è un’issue

Le issue sono perfette per task concreti: “il form non funziona”, “aggiungere la pagina contatti”. Ma ci sono situazioni dove un’issue non è lo strumento giusto:

❓
Domande
“Come funziona il sistema di autenticazione?” — non è un task, è una richiesta di spiegazione.
💡
Idee e proposte
“Che ne dite se aggiungiamo un blog?” — serve una discussione prima di creare un’issue.
📖
Documentazione
“Come si configura l’ambiente di sviluppo?” — serve una guida permanente, non un task da chiudere.

1.2 — La mappa: quale strumento per cosa

Situazione Strumento Perché
Bug da correggere, feature da implementare Issue Task concreto con inizio e fine, collegabile a PR e commit
Domanda, proposta, annuncio, sondaggio Discussion Conversazione aperta senza “chiusura”, thread e reazioni
Guida, tutorial, architettura, setup Wiki Documentazione strutturata e permanente, navigabile
Istruzioni brevi per iniziare README Prima cosa che si vede nel repository, always visible

1.3 — GitHub Discussions

GitHub Discussions è un forum integrato nel repository. È organizzato in categorie e supporta thread, reazioni, risposte accettate e sondaggi. È il posto giusto per conversazioni che non sono task.

Le categorie predefinite di Discussions
📣 Announcements
Solo i maintainer possono creare post. Per annunci ufficiali: “Versione 1.0 rilasciata!”, “Nuove regole del progetto”.
💬 General
Conversazioni generali sul progetto. “Come vi trovate con il nuovo layout?”
💡 Ideas
Proposte e idee per il futuro. “Che ne dite se aggiungiamo un sistema di commenti?” Se l’idea viene approvata, si converte in issue.
🗳️ Polls
Sondaggi con opzioni votabili. “Quale framework CSS usiamo? Bootstrap / Tailwind / Nessuno”.
🙏 Q&A
Domande con risposta accettabile. “Come faccio a far funzionare il dark mode?” Qualcuno risponde, l’autore segna la risposta come “accettata”.
🙌 Show and tell
Mostra qualcosa di interessante. “Guardate cosa ho costruito con il nostro progetto!”

Attivare Discussions

1
Repository → Settings → sezione “Features”.
2
Spunta “Discussions”. La tab appare nel repository.
3
Puoi personalizzare le categorie: Discussions → ⚙️ → “Categories” → crea, rinomina o elimina.

Funzionalità speciali delle Discussions

Funzione Come A cosa serve
Risposta accettata L’autore segna una risposta come “Answer” (solo in Q&A) Chi arriva dopo vede subito la soluzione, senza leggere tutto il thread
Reazioni Emoji sui post (👍 ❤️ 🎉 😄 🚀 👀) Esprimere accordo senza scrivere “sono d’accordo” — meno rumore
Converti in issue Menu ⋯ sulla discussione → “Convert to issue” Quando un’idea diventa un task concreto da implementare
Pin Menu ⋯ → “Pin discussion” Fissare discussioni importanti in cima alla lista
Poll (sondaggio) Nella categoria “Polls”, crei opzioni votabili Decidere in team: “Quale colore per il logo? Blu / Rosso / Verde”

1.4 — GitHub Wiki

La Wiki è uno spazio per documentazione strutturata — guide, tutorial, architettura, FAQ. A differenza del README (una singola pagina), la Wiki può avere molte pagine organizzate con una sidebar navigabile.

Quando usare la Wiki
✅ Guida all’installazione dettagliata
✅ Documentazione dell’architettura
✅ Glossario dei termini del progetto
✅ Convenzioni di codice
✅ FAQ per i nuovi contributori
✅ Tutorial passo per passo
Quando NON usare la Wiki
❌ Task da assegnare → usa Issue
❌ Discussioni e domande → usa Discussions
❌ Istruzioni brevi → usa README
❌ Documentazione inline nel codice → usa commenti
❌ Changelog → usa Release notes

Attivare e usare la Wiki

1
La Wiki è attiva di default. Vai alla tab “Wiki” nel repository.
2
La prima volta vedi “Welcome to the wiki!” — clicca “Create the first page”.
3
Scrivi la pagina in Markdown. Titolo della pagina = nome del file. Clicca “Save page”.
4
Per aggiungere altre pagine: “New page” (in alto a destra). Per la sidebar: crea una pagina speciale chiamata “_Sidebar” con i link alle altre pagine.

1.5 — Struttura consigliata per una Wiki scolastica

📚 Sidebar
→ Home
→ Installazione
→ Architettura
→ Guida di stile
→ FAQ
→ Il team
Contenuto delle pagine
Home
Panoramica del progetto, link alle sezioni principali
Installazione
Prerequisiti, comandi per clonare, installare dipendenze, avviare il progetto
Architettura
Struttura delle cartelle, tecnologie usate, diagramma dei componenti
Guida di stile
Convenzioni di naming, indentazione, struttura dei commit, regole CSS
FAQ
Domande frequenti con risposte — “Come faccio a…”, “Perché usiamo…”
Il team
Chi siamo, ruoli, link ai profili GitHub

La pagina _Sidebar

# Crea una pagina chiamata “_Sidebar” con questo contenuto:

## 📚 Navigazione

– [[Home]]
– [[Installazione]]
– [[Architettura]]
– [[Guida di stile]]
– [[FAQ]]
– [[Il team]]
La sintassi [[Nome pagina]] crea un link interno alla Wiki. La pagina _Sidebar appare automaticamente a lato di ogni pagina.

📌 La Wiki è un repository Git separato! Ogni Wiki ha il suo repository Git che puoi clonare: git clone git@github.com:utente/progetto.wiki.git. Puoi scrivere le pagine in locale con il tuo editor preferito, committare e pushare — esattamente come fai con il codice. Utile per modifiche massive o per chi preferisce lavorare offline.

1.6 — Discussions vs Issues: la regola pratica

Il test: “Si può chiudere?”
Sì → Issue
Ha un inizio e una fine. Qualcuno la prende, ci lavora, la chiude. Collegabile a un commit.
oppure
No → Discussion
È una conversazione aperta. Non c’è un “completato”. Serve per discutere, non per fare.
Esempio Issue? Discussion?
“Il pulsante di login non funziona su Safari” ✅ —
“Che ne dite se usiamo TypeScript invece di JavaScript?” — ✅
“Aggiungere validazione email al form di registrazione” ✅ —
“Come si configura l’ambiente di sviluppo su Windows?” — ✅ (Q&A)
“Quale colore usiamo per lo sfondo? Votiamo.” — ✅ (Poll)
“Grande lavoro ragazzi — v1.0 rilasciata!” — ✅ (Announce)

💻 2. Esempi guidati

Esempio A — Creare una Discussion “Ideas” e convertirla in issue

1
Tab Discussions → “New discussion” → Categoria: Ideas.
2
Titolo: “Proposta: aggiungere un blog al sito”. Corpo: “Mi piacerebbe aggiungere un blog dove ogni studente può pubblicare articoli. Potremmo usare Markdown per i post. Che ne pensate?”
3
I compagni commentano: “Bella idea!”, “Io preferirei un portfolio invece di un blog”, “Mi offro per farlo!”. Discussione in corso.
4
Dopo la discussione, il team decide: sì, facciamolo. L’autore clicca ⋯ → “Convert to issue”. L’idea diventa un’issue assegnabile con tutta la discussione preservata come contesto.

Esempio B — Creare una Wiki con 3 pagine

1
Tab Wiki → “Create the first page”. Titolo: Home. Contenuto:
# Sito della Classe 4A 🏫

Benvenuto nella documentazione del progetto!

## Pagine
– [[Installazione]] — Come far partire il progetto in locale
– [[Architettura]] — Struttura del progetto e tecnologie
2
Save page. Poi “New page” → Titolo: Installazione. Contenuto: prerequisiti, comandi git clone, npm install, come avviare il server.
3
Altra pagina → Titolo: Architettura. Contenuto: struttura cartelle, tecnologie usate, diagramma testuale.
4
Crea la pagina _Sidebar con i link: [[Home]], [[Installazione]], [[Architettura]]. Ora ogni pagina ha la navigazione laterale.

Esempio C — Sondaggio con Polls

1
Discussions → New discussion → Categoria: Polls.
2
Titolo: “Quale framework CSS per il progetto?”
3
Aggiungi le opzioni del sondaggio: Bootstrap, Tailwind CSS, CSS vanilla, Bulma.
4
Pubblica. I compagni votano cliccando la loro opzione preferita. Dopo 2-3 giorni, l’opzione con più voti vince. Decisione presa in modo democratico e documentato.

🏋️ 3. Esercizi

🟢 Esercizio 1 — Attiva Discussions e crea il primo post (Facile)

a) Attiva Discussions nel tuo repository (Settings → Features → Discussions).
b) Crea una discussione nella categoria “General” con un saluto al team: “Benvenuti nel nostro progetto!”.
c) Crea una discussione nella categoria “Q&A” con una domanda sul progetto.
d) Rispondi alla tua stessa domanda e segnala la risposta come “Answer”.
e) Aggiungi una reazione (emoji) a un post.

🔵 Esercizio 2 — Crea la Wiki del progetto (Medio)

a) Vai alla tab Wiki e crea la pagina Home con una panoramica del progetto.
b) Crea una pagina Installazione con i passi per far partire il progetto in locale (clone, dipendenze, avvio).
c) Crea una pagina Architettura con la struttura delle cartelle del progetto.
d) Crea la pagina _Sidebar con i link a tutte le pagine.
e) Naviga la Wiki: la sidebar appare a sinistra? I link funzionano?

🟠 Esercizio 3 — Da idea a issue (Medio)

a) Crea una discussione nella categoria “Ideas” con una proposta per il progetto.
b) Chiedi a un compagno (o simula tu) di commentare con feedback.
c) Dopo la “discussione”, converti la discussion in issue: ⋯ → “Convert to issue”.
d) L’issue creata ha un link alla discussione originale? La discussione ha un link all’issue?
e) Assegna l’issue e aggiungila al Project Board.

🟣 Esercizio 4 — Setup completo della comunicazione di team (Difficile)

Configura tutti gli strumenti di comunicazione per un progetto di gruppo:

a) Discussions: attiva e crea una categoria personalizzata “Decisioni di team” per le scelte importanti.
b) Crea una discussione pinned (Announcements): “Regole del progetto — leggere prima di iniziare”.
c) Crea un sondaggio (Poll): “Con quale frequenza facciamo stand-up? Ogni giorno / 2 volte a settimana / 1 volta a settimana”.
d) Wiki: crea 4 pagine (Home, Installazione, Guida di stile, FAQ) + _Sidebar.
e) Nella pagina “Guida di stile” della Wiki, documenta: naming dei branch, formato dei commit, regole CSS.
f) Nella FAQ, aggiungi almeno 3 domande e risposte che un nuovo membro del team potrebbe avere.
g) Condividi il link della Wiki con il team.

❓ 4. Quiz di verifica

1. Come decidi se usare un’issue o una discussion?

Mostra risposta

Il test è: “Si può chiudere?”. Se la risposta è sì — è un task concreto con inizio e fine (bug da correggere, feature da implementare) — usa un’issue. Se la risposta è no — è una conversazione aperta, una domanda, un’idea, un annuncio, un sondaggio — usa una discussion. Le issue sono per fare; le discussion sono per parlare. Se durante una discussion emerge un task concreto, puoi convertire la discussion in issue con un click.

2. Cosa fa “Convert to issue” su una Discussion?

Mostra risposta

Crea una nuova issue a partire dalla discussion, preservando il titolo e il contenuto. La discussion originale viene collegata all’issue con un link bidirezionale: nell’issue vedi il link alla discussione (contesto), nella discussione vedi il link all’issue (azione). È il workflow ideale per le idee: prima discuti (Discussion → Ideas), poi se il team decide di procedere, converti in issue (task assegnabile e tracciabile).

3. Cos’è la pagina _Sidebar nella Wiki e a cosa serve?

Mostra risposta

È una pagina speciale che viene mostrata a lato di ogni pagina della Wiki come menu di navigazione. Senza _Sidebar, ogni pagina è isolata — il lettore non sa quali altre pagine esistono. Con _Sidebar, hai una navigazione permanente con link a tutte le sezioni. La sintassi per i link interni è [[Nome pagina]]. Il nome deve corrispondere esattamente al titolo della pagina di destinazione. La _Sidebar è una pagina Wiki normale — si crea con “New page” e titolo “_Sidebar”.

4. In cosa differisce la Wiki dal README?

Mostra risposta

Il README è un singolo file (README.md) che appare nella pagina principale del repository — è la “copertina” del progetto, perfetta per una panoramica breve. La Wiki è uno spazio con molte pagine organizzate con navigazione — perfetta per documentazione dettagliata e strutturata. Il README è sempre visibile (sotto la lista dei file), la Wiki è in una tab separata. In pratica: il README dice “cos’è e come iniziare”, la Wiki dice “come funziona nel dettaglio”. Per progetti piccoli, basta il README. Per progetti medi-grandi, servono entrambi.

5. Come si clona la Wiki per lavorarci in locale?

Mostra risposta

La Wiki è un repository Git separato con URL che termina in .wiki.git. Per clonarla: git clone git@github.com:utente/progetto.wiki.git. Ogni pagina della Wiki è un file Markdown nella cartella. Puoi modificare i file in locale con il tuo editor, committare e pushare — le modifiche appaiono immediatamente nella Wiki su GitHub. Questo è utile per modifiche massive o per chi preferisce lavorare offline con un editor di testo piuttosto che nell’interfaccia web di GitHub.

6. Qual è la differenza tra la categoria “Q&A” e “General” nelle Discussions?

Mostra risposta

In Q&A, l’autore della discussione può segnare una risposta come “Answer” — la risposta accettata viene evidenziata in verde e appare in cima, così chi arriva dopo vede subito la soluzione senza leggere tutto il thread. La discussione viene anche contrassegnata come “Answered”. In General, non c’è il concetto di risposta accettata — è una conversazione libera dove tutti i commenti hanno lo stesso peso. Usa Q&A per domande con una risposta definita, General per discussioni aperte senza una risposta “giusta”.

📚 Riepilogo della lezione

Cosa hai imparato oggi:
  • La regola: “Si può chiudere?” → Issue. Altrimenti → Discussion.
  • Discussions: forum integrato con categorie (Announcements, General, Ideas, Q&A, Polls, Show and tell)
  • Q&A ha risposte accettabili; Polls ha sondaggi votabili
  • “Convert to issue”: un’idea discussa diventa un task concreto con un click
  • Wiki: documentazione strutturata in più pagine con navigazione
  • Pagina _Sidebar: menu laterale con link [[Nome pagina]]
  • La Wiki è un repo Git separato — clonabile e modificabile in locale
  • Mappa: Issue = task · Discussion = conversazione · Wiki = documentazione · README = panoramica
🎉
Giro di boa: Lezione 23 di 45!
Sei a metà corso. Fermati un momento a pensare a quanto hai imparato: parti da zero con Git e ora sai gestire branch, merge, conflitti, rebase, PR con code review, fork, branch protection, Projects, milestone, release, discussions e wiki. Il peggio è passato — le basi sono solidissime. Da qui in avanti, tutto si costruisce su ciò che già sai.

Prossima lezione →

Lezione 24 — Template per Issue e PR
Standardizzare la comunicazione del team. Template avanzati con YAML.
PR template. Automatizzare le convenzioni.

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