GitHub, pull request e il vostro codice in Checkmk

Poco prima della Checkmk Conference #9, ci è sembrato giusto gettare uno sguardo indietro verso l'anno passato. A mio modesto parere, uno dei grandi successi della nostra collaborazione con la comunità è stato il miglioramento del processo di revisione delle pull request su GitHub.

Ogni giorno, per mantenere Checkmk al passo con le esigenze dei nostri utenti, il team di sviluppo (alias i manutentori di Checkmk) deve dare priorità ad alcuni compiti rispetto ad altri, tra cui la creazione di nuovi check e l'aggiornamento di quelli esistenti, il miglioramento della sicurezza, la progettazione di nuove funzionalità, la correzione di bug e il rilascio di nuove versioni. Deve anche trovare il tempo di comunicare con i collaboratori, rivedendo le pull request su GitHub e commentando ciò che potrebbe essere migliorato.

Prima di maggio 2022, non era facile per il team tenere il passo con tutti i contributi inviati, il che portava a ritardi nelle revisioni e a incomprensioni. Pur apprezzando molto la disponibilità delle persone ad aiutare, era evidente che fosse necessario modificare qualcosa nel processo affinché gli sforzi di tutti diventassero più produttivi. Ecco cosa abbiamo fatto.

Innanzitutto, abbiamo istituito un processo dedicato, in modo che i contributi di codice potessero ricevere la cura e l'attenzione che meritano. Abbiamo creato regole affinate, che ci aiutano a decidere se la pull request debba essere assegnata agli sviluppatori per l'implementazione o se, al contrario, debba essere rifiutata, ad esempio nei casi in cui non segua le linee guida per i contributi.

Abbiamo istituito un sistema in cui prestiamo un'attenzione sistematica alle pull request e prendiamo decisioni sulla loro chiusura. Questo accade principalmente se le modifiche non sono conformi agli standard del codice Checkmk o perché una determinata modifica non appare quella giusta da apportare al momento. Le modifiche devono anche essere conformi alle linee guida aggiornate. Con tutti questi cambiamenti, siamo riusciti a ridurre i tempi di elaborazione delle richieste a poche settimane, o meno. Nel momento in cui sto scrivendo questo articolo, vedo solo 20 richieste aperte. Come parte del team di manutentori dietro Checkmk, posso dire che siamo soddisfatti dei progressi fatti lo scorso anno. Ma cerchiamo sempre di migliorare, ed ecco come voi - in qualità di contributori di codice - potreste aiutarci.

Di seguito condivido un paio di dettagli del nuovo processo, che potete seguire per aumentare le probabilità che la vostra PR venga accettata. Alcuni di questi approfondimenti potrebbero anche aiutare a capire perché una modifica non è stata approvata anche se segue perfettamente le regole e potrebbe portare valore al progetto.

Come già detto, uno dei criteri principali per l'approvazione di una pull request è che questa segua le linee guida per i contributi. Ci sono diversi motivi per cui è così importante:

Innanzitutto, le guide di stile. Qualsiasi codice sorgente deve essere leggibile (per chi conosce la lingua) e ordinato, in modo che ogni volta che quella parte di codice deve essere aggiornata o cambiata completamente, tutti possano capirla. È come per i libri: un'impaginazione coerente è la strada da seguire se si vuole godere della lettura o continuare a scrivere. Per questo motivo saranno accettati solo i contributi che seguono la guida di stile.

Un'altra cosa è il processo che utilizziamo per il commit delle modifiche e il loro test attraverso il CI. Come per le guide di stile, i messaggi di commit devono essere chiari e devono essere inviati attraverso la corretta procedura git - il team si è impegnato molto per scrivere tutti i passaggi, quindi dovrebbe essere la parte più facile. I test sono essenziali: se la modifica non supera i test, significa che non funziona correttamente. In questo caso, si prega di correggere il codice se si vuole che venga approvato.

"Divide et impera": questo motto non funziona solo in politica, ma anche nelle pull request. Le modifiche brevi e precise che affrontano un problema specifico o una parte di esso sono le più facili da revisionare, perché il processo richiederà meno tempo. Un'altra ragione è che più si divide una grande idea in modifiche più piccole, maggiore è la possibilità che almeno alcune di queste modifiche più piccole vengano approvate.

Il team semplicemente non può allocare risorse sufficienti per revisionare richieste lunghe: una buona e completa revisione richiede tempo e concentrazione, elementi molto difficili da garantire entrambi in presenza di modifiche complesse all'interno di una richiesta. Un altro argomento a favore di modifiche separate in PR distinte è che ogni PR avrà un contesto migliore nella descrizione, il che consente al revisore di comprendere meglio la vostra idea. Quindi, per favore, cercate di essere precisi, di fornirci il contesto e, così facendo, aiutateci a convalidare il vostro contributo e ad accettarlo più facilmente.

Alcune modifiche, ad esempio correzioni o rifattorizzazioni, richiedono davvero la modifica del codice sorgente e il passaggio attraverso il processo di revisione delle pull request. Ma per molte funzioni, caricarle su Checkmk Exchange potrebbe essere un'opzione migliore. Perché? Il processo di revisione è meno complicato, potrete continuare ad apportare modifiche aggiungendo nuove versioni del pacchetto e riceverete sicuramente l'apprezzamento diretto della comunità, e allo stesso tempo manterrete la proprietà del vostro pacchetto.

A volte riceviamo ottimi contributi, ma dobbiamo rifiutarli per un motivo che potrebbe non sembrare così ovvio. Alcune modifiche potrebbero funzionare in integrazione con uno strumento molto specifico che non abbiamo tra le mani e quindi non possiamo convalidarle. Per esempio, se create una pull request che implementa un'integrazione con qualche istanza esotica di Oracle cui non abbiamo accesso, non possiamo testarla - anche se voi potete, noi non possiamo. E come team che non solo mantiene Checkmk ma si assume anche la responsabilità del progetto, non possiamo in coscienza accettare una modifica del genere, anche se la riteniamo utile. In casi come questo, raccomandiamo ancora una volta di caricare la modifica come pacchetto Exchange.

Un altro caso è quello in cui la modifica viene testata e funziona per voi, ma non per altri. Non potremo accettare tali modifiche, perché dobbiamo considerare il progetto e tutti i suoi utenti nel loro insieme.

Si noti che più il team di sviluppatori si impegna, più contributi abbiamo e più pull request riceviamo. Per questo motivo è molto importante seguire la discussione con i rappresentanti del team di sviluppo nei commenti alle PR, e avere pazienza se ci vuole un po' più di tempo per esaminare la vostra richiesta. Abbiamo a cuore e apprezziamo ogni contributo, per questo vogliamo dedicargli il tempo che merita per assicurarci che diventi una parte organica di Checkmk.

Ci auguriamo che le modifiche e le regole più trasparenti per le pull request ci permettano di collaborare maggiormente, consentendovi di inviare più comodamente le modifiche e di farcele controllare e accettare. Nel grafico qui sotto, potete vedere come il nostro tasso di risposta alle pull request sia aumentato nell'ultimo anno - e crediamo di poter fare ancora meglio andando avanti. Speriamo di continuare ad avervi ancora, numerosi, con noi in questo viaggio.