Come maintainer, rivedere i pull request è qualcosa che farai abbastanza regolarmente.
Questo documento contiene alcune linee guida per la revisione dei pull request specifiche di Exercism.
Revisione dei pull request degli esercizi
Rivedere un pull request per un esercizio sui concetti o un esercizio di pratica può essere scoraggiante, viste le tante regole che riguardano questi tipi di esercizio.
Per questo motivo, una prima revisione da parte di un maintainer richiede spesso due o tre ore e produce decine di commenti.
Per gli esercizi sui concetti ci sono anche file con obiettivi e contenuti simili (ad esempio l'introduzione all'esercizio e quella al concetto): qui è essenziale concentrarsi prima sul rendere perfetto uno di questi, prima di spingersi troppo oltre.
Per aiutare a snellire questo flusso di lavoro, abbiamo sviluppato le seguenti raccomandazioni.
Raccomandazione: affidare la prima revisione ad un solo maintainer senior
I motivi per cui la prima revisione dovrebbe essere affidata ad un solo maintainer senior sono:
- Non si duplica il lavoro di revisione
- Il contributore e il maintainer lavoreranno in coppia sul pull request, e questo, si spera, darà al contributore la sensazione di non essere solo in questo
- Non ci saranno commenti di revisione contraddittori da parte di altri maintainer
Raccomandazione: fare il merge con lo stato wip
Una volta che il contributore e il maintainer sono entrambi soddisfatti dell'esercizio, bisogna fare il merge dell'esercizio con il suo status impostato a wip (lavori in corso).
Gli esercizi con questo stato non saranno disponibili per gli studenti, ma potranno essere visualizzati dai nostri mentori migliori (una volta che avremo implementato questa cosa, prima o poi in futuro).
Questi utenti con alta reputazione potranno allora testare l'esercizio e creare issue o pull request per correggere o migliorare l'esercizio.
I principali vantaggi di questo approccio sono:
- Rimuove l'onere, per la coppia originale contributore/maintainer, di rendere tutto perfetto
- Non porta ad enormi cicli di pull request con molte voci diverse (che sono davvero difficili da gestire)
Revisione dei pull request degli esercizi di pratica
Raccomandazione: valutare se la modifica appartiene davvero a problems-specifications
Alcuni contenuti di un esercizio di pratica (come la sua introduzione) provengono dai suoi metadati (condivisi) definiti nel repo problems-specifications.
Quando rivedi un pull request che modifica tali contenuti, valuta se la modifica potrebbe giovare anche ad altri track.
In tal caso, suggerisci al contributore di aprire un pull request per il file corrispondente nel repo problems-specifications
Raccomandazioni generali per la revisione
Raccomandazione: un revisore principale per ogni pull request
Ogni pull request dovrebbe avere un revisore principale (qualunque maintainer se ne occupi).
Gli altri maintainer e/o i membri della comunità dovrebbero avere un ruolo secondario.
Ci sono due modi principali in cui qualcuno con un ruolo secondario può contribuire ad una revisione:
- Correggere ortografia e grammatica, ma solo dopo che è avvenuta la prima revisione da parte del revisore principale.
Può essere frustrante per i contributori ricevere una revisione di ortografia e grammatica, sistemarla, e poi vedere arrivare un maintainer che chiede loro modifiche più sostanziali.
In altre parole: la correzione di bozze è qualcosa che fai dopo che le modifiche sostanziali sono state sistemate (o magari in un pull request successivo).
- Segnalare le cose al revisore in modo non vincolante.
Se commenti cose a cui il revisore principale dovrebbe pensare o che potrebbe aver tralasciato, pubblica il tuo commento come affermazione di un'opinione o sotto forma di domanda.
Così è chiaro al contributore che non gli stai chiedendo di fare modifiche, il che renderà le cose meno confuse per lui.
Ridurrà anche la probabilità che il revisore principale si senta «sminuito».
Quando rivedi un pull request, commenta solo le cose direttamente collegate al pull request.
Per tutto il resto, apri una issue o crea un pull request separato (di follow-up).
Raccomandazione: linkare la documentazione
Quando possibile, cerca sempre di linkare la documentazione che spiega il motivo per cui stai commentando qualcosa.
Questo aiuta molto a ridurre il rischio che le cose diventino polemiche.
Raccomandazione: chiedere aiuto ad altri team
Se vuoi chiedere aiuto per rivedere un pull request, ci sono due team specifici che puoi menzionare:
-
@exercism/reviewers: per qualsiasi revisione generale
-
@exercism/github-actions: per qualsiasi domanda riguardante le GitHub actions
