Tre posti per la documentazione, tre scopi diversi
GitHub mette a disposizione tre spazi distinti per scrivere e condividere contenuti, e l’esame verifica soprattutto che tu sappia scegliere quello giusto a partire dallo scenario descritto nella domanda.
Un gist è il posto dei frammenti. Serve a condividere un pezzo di codice, uno script, un file di configurazione, senza costruirci intorno un progetto. Ogni gist è a tutti gli effetti un repository Git: si può clonare, si può fare fork, e conserva la cronologia completa dei commit con i relativi diff. Esistono in due visibilità. Un public gist compare in Discover ed è ricercabile; un secret gist non compare in Discover e non è ricercabile, ma chiunque riceva l’URL può aprirlo. Qui sta la confusione tipica da evitare: secret non significa privato. Se ti serve riservatezza vera, un gist non è lo strumento adatto. Nota anche che la conversione è a senso unico: un secret gist può diventare public, mentre un public gist non può tornare secret.
Il wiki è invece la sezione dedicata alla documentazione lunga, presente in ogni repository. La divisione di ruoli con il README è netta: il README dice in fretta che cosa fa il progetto, mentre il wiki ospita il contenuto esteso, cioè come si usa il progetto, come è stato progettato, quali principi lo guidano. Anche il wiki è un repository Git separato: si modifica dal browser oppure in locale. Di default solo chi ha write access sul repository può modificarlo, però su un repository pubblico il proprietario può aprire il contributo a chiunque su GitHub.com. In un repository privato il wiki resta visibile soltanto a chi ha accesso al repository.
Pubblicare un sito con GitHub Pages
GitHub Pages è un servizio di hosting per siti statici: prende i file HTML, CSS e JavaScript direttamente da un repository e li pubblica come sito web. I siti sono di due tipi. Il user site o organization site, uno solo per account, risponde all’indirizzo nomeaccount.github.io. Il project site, uno per repository, risponde a nomeaccount.github.io/nomerepository.
Quello che devi saper riconoscere è il publishing source, cioè da dove Pages prende i file. Si configura in Settings, nella sezione Code and automation, alla voce Pages, sotto Build and deployment. Le due opzioni sono Deploy from a branch, dove scegli il branch e come cartella la radice del repository oppure /docs, e GitHub Actions, dove un workflow costruisce e pubblica il sito. La seconda serve quando c’è un passaggio di build o quando non vuoi versionare i file compilati. Attenzione: Pages serve contenuti statici, non applicazioni con logica lato server.
Insights: che cosa raccontano i grafici del repository
La scheda Insights raccoglie i grafici del repository. Pulse riassume l’attività di un periodo, Contributors mostra chi ha committato, Commits e Code frequency raccontano il ritmo del progetto e il volume di righe aggiunte e rimosse. Network e Forks mostrano i rapporti con i repository derivati, mentre il dependency graph elenca il codice da cui il tuo repository dipende.
Il grafico Traffic è quello su cui si sbaglia più spesso: è visibile solo a chi ha push access al repository, quindi un visitatore qualsiasi non lo vede. Mostra i clone completi, che sono cosa diversa dai fetch, il numero di visitors e di unique visitors, i referring sites e i popular content, su una finestra mobile di due settimane. Su GitHub Free alcuni di questi grafici sono disponibili solo nei repository pubblici; nei piani a pagamento compaiono anche nei privati.
Le star non sono una metrica di traffico. Servono come segnalibro per ritrovare un progetto e come segnale di apprezzamento verso chi lo mantiene; influenzano i suggerimenti della dashboard e i ranking di popolarità. Si possono creare lists pubbliche per organizzare i repository salvati. La star non concede alcun permesso, e non va confusa con il watch, che governa le notifiche.
Template repository, branch e buona manutenzione
Un template repository si attiva da Settings ed è pensato per far partire progetti nuovi da uno scheletro comune. Chi crea un repository da template ottiene una copia che parte da un singolo commit, con il solo default branch a meno di selezionare Include all branches, con visibilità scelta in modo indipendente e con i commit che contano nel contribution graph. La conseguenza da ricordare è che le due storie sono unrelated histories: non puoi aprire pull request né fare merge fra il template e il repository che ne deriva. Il fork, al contrario, porta con sé l’intera cronologia ed è la strada per riproporre le modifiche al progetto originale. La regola pratica per l’esame: se lo scenario dice “contribuire a un progetto esistente” la risposta è fork, se dice “avviare progetti nuovi partendo da una struttura standard” è template.
Sulla manutenzione, le pratiche documentate sono poche e costanti: README, licenza, linee guida per i contributi, code of conduct e un file SECURITY.md per segnalare le vulnerabilità; per i collaboratori abituali lavorare a branch nello stesso repository invece che a fork; proteggere i branch importanti con branch protection, richiedendo review e status check; usare Git LFS per i file di grandi dimensioni.