Tre strumenti, tre domande diverse
Il criterio di scelta è più semplice di quanto sembri: conta che cosa stai chiedendo a chi legge.
Un issue serve a tracciare un lavoro — un bug, un’attività, una proposta di miglioramento. Vive dentro un singolo repository, ha di norma un proprietario e uno stato che prima o poi si chiude. Lo si organizza con label, milestone, assignees e sub-issues, e questi metadati sono poi riutilizzabili nelle viste di Projects.
Una pull request serve a proporre modifiche concrete: contiene un diff, si commenta riga per riga, passa per una review e finisce con un merge o una chiusura. Se la domanda è “va bene questa modifica?”, lo strumento è la pull request, non l’issue.
Le discussions servono alle conversazioni aperte che non hanno né un proprietario né un esito azionabile: domande d’uso, idee, annunci, sondaggi. Sono organizzate in categories; in quelle di tipo question and answer una risposta può essere marcata come answer, e una conversazione si può fissare con pin o chiudere con lock. Vanno abilitate da un amministratore e possono esistere anche a livello di organizzazione, quindi oltre il confine del singolo repository. Un issue che si rivela una domanda e non un lavoro da fare si può convertire in discussion.
Ecco che cosa l’esame verifica davvero su questo punto: dato uno scenario, saper scegliere lo strumento. “Un utente chiede come si configura una funzionalità” è discussions; “il pulsante non funziona” è issue; “ho già scritto la correzione” è pull request.
Collegare una pull request a un issue
Nel corpo della pull request si scrive una closing keyword seguita dal riferimento all’issue, per esempio “Fixes #12”. Le parole accettate sono nove, tre famiglie da tre forme ciascuna: close, closes, closed; fix, fixes, fixed; resolve, resolves, resolved. Per un issue in un altro repository la sintassi diventa “Fixes owner/repository#12”.
Due dettagli che l’esame ama chiedere. Primo: la chiusura automatica avviene solo se la pull request viene unita al default branch. Se la pull request punta a un altro branch le parole chiave vengono ignorate, non si crea alcun collegamento e il merge non tocca l’issue. Secondo: una closing keyword scritta in un commit message chiude sì l’issue al merge, ma non marca la pull request come collegata.
In alternativa esiste il collegamento manuale dalla sezione Development nella barra laterale. Dalla pull request si collegano issue dello stesso repository; dall’issue si collegano pull request o branch anche di altri repository. Solo i collegamenti creati a mano si possono sciogliere a mano: per rimuovere un legame nato da keyword bisogna modificare la descrizione.
Template, assegnatari, label e filtri
Gli issue templates vivono in .github/ISSUE_TEMPLATE sul default branch, in due forme. I file Markdown precompilano il testo e dichiarano name e about nel frontmatter. Le issue forms in YAML presentano invece campi strutturati e permettono di renderne alcuni obbligatori, così chi apre l’issue non dimentica la versione o i passi per riprodurre il problema. Il file config.yml nella stessa cartella governa il template chooser: blank_issues_enabled decide se lasciare aperta l’opzione dell’issue vuoto, contact_links indirizza altrove chi cerca supporto. Il pull request template è invece un file singolo, che può stare nella radice del repository, in docs o in .github, con estensione .md o .txt e nome non case sensitive.
Sugli assignees, possono essere assegnati te stesso, chi ha già commentato, chi ha permesso write e i membri dell’organizzazione con permesso read. Attenzione al ruolo triage, ricorrente nelle domande: può applicare label e milestone, assegnare, chiudere e riaprire, richiedere review, ma non può creare o modificare le label — per quello serve write.
I filtri sono qualificatori di ricerca componibili: is:issue e is:pr, state:open, author:, assignee:, mentions:, involves:, label:, milestone:, review-requested:. Molto utili i negativi no:label, no:assignee, no:milestone e la coppia linked:pr e linked:issue, che isola gli elementi con o senza collegamento. Si combinano con AND, OR e parentesi, e l’URL della pagina si aggiorna da solo: una vista filtrata è quindi condivisibile come semplice link.
Notifiche: watch, subscribe e follow
Watch si applica al repository intero. Puoi seguire tutta l’attività, ignorarla, oppure scegliere in modo personalizzato per tipo di evento: issues, pull requests, releases, discussions, security alerts.
La subscription al singolo thread è un’altra cosa e spesso avviene senza che tu la richieda: sei sottoscritto se apri un issue o una pull request, se commenti, se vieni assegnato, se sei citato con una @mention (anche tramite un team), se cambi lo stato di una conversazione chiudendo un issue o unendo una pull request, oppure se premi Subscribe a mano. Unwatch e unsubscribe agiscono su livelli diversi: smettere di seguire un thread lo toglie dalla inbox, ma una nuova @mention te lo riporta.
Le notifiche arrivano nella inbox su github.com/notifications, in GitHub Mobile e via email, e nella inbox si filtrano per motivo, per esempio reason:review-requested.
Ultima trappola, quasi garantita all’esame: seguire una persona con follow ti mostra la sua attività pubblica nel dashboard, ma non è una sottoscrizione alle notifiche. Chi vuole essere avvisato delle novità di un progetto deve fare watch sul repository, non follow sull’autore. Allo stesso modo lo star è un segnalibro, non un canale di notifica.