Markdown, GitHub Desktop e GitHub Mobile
Su GitHub quasi tutto il lavoro passa da un campo di testo: la descrizione di un issue, il corpo di una pull request, un commento di review. Quel campo non accetta testo semplice, ma GitHub Flavored Markdown, il dialetto di Markdown che GitHub usa per formattare prosa e codice in tutto il sito. Saperlo usare è la differenza fra una segnalazione che nessuno riesce a leggere e una che il manutentore prende in carico subito. Poi vedremo i due casi in cui conviene uscire dal browser: GitHub Desktop e GitHub Mobile.
Formattare: intestazioni, liste, codice e task list
Le headings si scrivono anteponendo da uno a sei caratteri # al titolo. Quando un documento contiene almeno due intestazioni, GitHub genera in automatico un sommario navigabile, raggiungibile dal menu Outline.
Le liste non ordinate iniziano con -, * o +; quelle ordinate con un numero seguito da un punto. Per annidare una sotto-voce basta rientrarla sotto il testo della voce superiore.
Per il codice ci sono due forme: i backtick singoli per il code inline dentro una frase, e i tre backtick di apertura e chiusura per un blocco di codice su più righe, dove si può dichiarare il linguaggio per ottenere l’evidenziazione della sintassi. È il modo corretto di incollare un errore o un frammento di configurazione in un issue: senza backtick, Markdown mangia gli asterischi, i trattini e le indentazioni, e il log diventa illeggibile.
La task list si scrive con - [ ] per una voce da fare e - [x] per una completata. Nella vista renderizzata le caselle sono spuntabili con un clic, senza riaprire il testo in modifica: per questo le task list sono lo strumento naturale per la checklist di una pull request o per spezzare un issue in passi.
Servono anche il carattere > per citare testo e i cinque alerts che GitHub aggiunge alla citazione, cioè > [!NOTE], > [!TIP], > [!IMPORTANT], > [!WARNING] e > [!CAUTION], da usare con parsimonia. Le immagini si allegano trascinandole nel campo commento. E se la sintassi non ti torna in mente, ogni campo commento ha sopra una barra di formattazione che la inserisce al posto tuo.
Menzioni, riferimenti e parole chiave di chiusura
Qui GitHub va oltre il Markdown standard. Scrivendo @username menzioni una persona e le mandi una notifica, ma solo se quella persona ha almeno accesso in lettura al repository. Con @organizzazione/nome-team menzioni un intero team; se il team menzionato ha dei team figli, la notifica arriva anche ai loro membri.
Digitando # compare l’autocompletamento di issue e pull request del repository: puoi filtrare per numero o per titolo e confermare con Tab o Invio. Il riferimento diventa un collegamento e lascia una traccia nella cronologia dell’elemento citato, così le due conversazioni restano collegate.
Nella descrizione di una pull request valgono inoltre le closing keyword close, closes, closed, fix, fixes, fixed, resolve, resolves e resolved, seguite dal riferimento all’issue, per esempio Closes #10. Al merge l’issue si chiude da sola. Attenzione al limite: queste parole chiave vengono interpretate solo quando la pull request punta al default branch del repository. Per un issue di un altro repository la forma è Fixes proprietario/repository#100. Se le stesse risposte ti servono spesso, le saved replies sono legate al tuo account personale e restano disponibili in tutti i repository e le organizzazioni.
L’esame non ti chiede di scrivere Markdown a mano: ti chiede di riconoscere quale sintassi produce quale effetto e a che cosa serve. La confusione più frequente è fra il semplice riferimento #123, che collega e basta, e la closing keyword, che collega e chiude al merge.
Quando conviene GitHub Desktop
GitHub Desktop è un’applicazione gratuita e open source per Windows e macOS che lavora sui file ospitati su GitHub o su altri servizi di hosting Git. Dà un’interfaccia grafica ai comandi Git: clonare un repository sul computer, creare un branch, fare commit, fare push, aggiungere co-autori a un commit, scegliere quali righe far entrare in un commit, controllare la cronologia e fare il checkout di una pull request per provarla in locale.
È pensato per chi trova scomoda la riga di comando o vuole vedere le differenze prima di confermarle. Non è un editor di codice e non sostituisce l’ambiente di sviluppo: continui a modificare i file con il tuo editor abituale e usi Desktop per la parte Git.
Che cosa si può fare da GitHub Mobile
GitHub Mobile è l’app per Android e iOS. Serve a gestire, smistare e azzerare le notifications, a leggere e commentare issue e pull request collaborando alla discussione, a modificare file dentro una pull request, a cercare e sfogliare utenti, repository e organizzazioni e a cercare nel codice di un repository. Include Copilot Chat per fare domande, permette di verificare i tentativi di accesso da dispositivi non riconosciuti come secondo fattore di autenticazione e consente di restare connessi con più account, anche di GitHub Enterprise Server.
Il criterio da portare all’esame è semplice: Mobile serve a non bloccare i colleghi quando sei lontano dalla scrivania (approvare, rispondere, smistare), Desktop serve a lavorare sui file in locale con Git senza terminale, il browser resta il posto dove si amministra il repository.