La struttura di un repository e i suoi file chiave
Un repository contiene tutto il codice di un progetto, i suoi file e la cronologia delle revisioni di ciascuno di essi. Accanto al codice vero e proprio, GitHub riconosce un piccolo insieme di file speciali: non sono obbligatori, ma quando esistono la piattaforma li interpreta e li mostra in punti precisi dell’interfaccia. Sono i community health file, ed è proprio su questi che l’esame ti chiede di saper distinguere ruolo e collocazione.
Vale una regola generale prima dei dettagli. Per la maggior parte di questi file GitHub guarda in tre posizioni: la cartella .github, la radice del repository e la cartella docs, usando la prima in cui trova una corrispondenza. Non ci sono percorsi alternativi da inventare: se il file sta altrove, non viene riconosciuto e resta un normale file di testo. È una confusione tipica in aula, e una domanda facile da sbagliare se si risponde “ovunque nel repository”.
README, CONTRIBUTING e SECURITY: i file che parlano alle persone
Il README è il biglietto da visita del progetto: spiega che cosa fa, perché è utile e come si comincia a usarlo. GitHub lo mostra automaticamente sotto l’elenco dei file nella pagina principale del repository, lo interpreta come Markdown e genera un indice navigabile a partire dalle intestazioni. Conviene usare link relativi invece di URL assoluti, così i rimandi continuano a funzionare anche dopo un clone. Un caso particolare da ricordare: un repository pubblico che porta lo stesso nome del tuo account mostra il proprio README direttamente sul profilo GitHub, ed è il cosiddetto profile README.
Il file CONTRIBUTING descrive come si contribuisce al progetto: convenzioni per i commit, come proporre una pull request, quali informazioni servono in una issue. Il suo valore non è solo documentale: quando qualcuno apre una issue o una pull request, GitHub gli mostra un link a quel file, e le linee guida compaiono anche nella pagina Contribute del repository. Il nome non è sensibile alle maiuscole.
Il file SECURITY contiene la security policy: indica ai collaboratori come segnalare una vulnerabilità trovata nel progetto e incoraggia una divulgazione responsabile. È il canale che eviti di ricevere una segnalazione di sicurezza dentro una issue pubblica, dove sarebbe visibile a chiunque prima della correzione.
Sia CONTRIBUTING sia SECURITY, come gli altri community health file, possono essere definiti una sola volta a livello di organizzazione o di account personale, in un repository dedicato chiamato .github: da lì valgono come default per tutti i repository che non hanno una versione propria.
LICENSE e CODEOWNERS: i file che decidono che cosa si può fare
Il file LICENSE è l’unico che ha effetti giuridici, ed è il punto su cui l’esame insiste di più. Senza un file di licenza si applica il diritto d’autore predefinito: l’autore mantiene tutti i diritti e nessun altro può riprodurre, distribuire o creare opere derivate dal codice. Attenzione alla trappola classica: questo vale anche se il repository è pubblico. Pubblico significa soltanto che i termini di servizio di GitHub consentono a chiunque di visualizzare il repository e di farne un fork sulla piattaforma; non significa open source e non concede alcun permesso di riuso. È la licenza a concederlo, e la licenza deve esserci come file.
Il file va posto nella radice del repository con un nome come LICENSE, LICENSE.md o LICENSE.txt. GitHub confronta il testo con le licenze note e, quando la riconosce, la espone in evidenza nella pagina principale del repository. Citare la licenza solo nel README è considerato insufficiente: serve il file. Per scegliere, il riferimento indicato dalla documentazione è choosealicense.com, ricordando che GitHub non fornisce consulenza legale.
Il file CODEOWNERS assegna a persone o team la responsabilità di determinati percorsi del repository. Quando una pull request tocca quei file, la review viene richiesta automaticamente ai code owner indicati. Tre punti che l’esame ama verificare: il file deve trovarsi nella radice, in .github o in docs; deve esistere sul branch di destinazione della pull request, perché ogni branch può avere il proprio; e i code owner devono avere almeno il permesso write sul repository, i team compresi, altrimenti la riga viene ignorata. La sintassi segue le regole di gitignore e, in caso di più corrispondenze, vince l’ultima riga che combacia. Da sola CODEOWNERS non blocca nulla: serve una regola di branch protection che richieda l’approvazione dei code owner, e in quel caso basta l’approvazione di uno degli owner elencati, non di tutti.
Aggiungere e modificare file nel repository
Dal browser il punto d’ingresso è il menu Add file nella pagina del repository, con le voci Create new file e Upload files; quest’ultima accetta anche il trascinamento diretto dei file. Creando un file chiamato LICENSE compare il pulsante Choose a license template, che inserisce il testo completo della licenza scelta. In fondo alla pagina si scrive il messaggio di commit e si sceglie fra Commit directly sul branch corrente e la creazione di un nuovo branch con apertura di una pull request. Se il branch è protetto, la modifica diretta dal web viene rifiutata. Il caricamento dal browser ha inoltre un limite di dimensione per file più basso rispetto alla riga di comando, e per i file molto grandi occorre Git Large File Storage.
Dalla riga di comando il flusso è quello di Git: si copia o si modifica il file nella copia locale, si mette in staging con git add, si registra la modifica con git commit -m e la si invia con git push. Il risultato è identico a quello ottenuto dal web, perché in entrambi i casi si sta producendo un commit sul branch scelto.