Enquanto maintainer, vais rever pull requests com bastante regularidade.
Este documento contém algumas orientações de revisão de pull requests específicas do Exercism.
Rever pull requests de exercícios
Rever um pull request de um exercício de conceito ou de um exercício de prática pode ser intimidador, dada a quantidade de regras em torno deste tipo de exercício.
Por este motivo, uma primeira revisão por parte de um maintainer demora muitas vezes duas a três horas e resulta em dezenas de comentários.
Nos exercícios de conceito, há também ficheiros com objetivos e conteúdos semelhantes (por exemplo, a introdução do exercício e a introdução do conceito), em que é essencial concentrares-te primeiro em deixar um deles perfeito antes de te dispersares demasiado.
Para ajudar a simplificar este fluxo de trabalho, desenvolvemos as seguintes recomendações.
Recomendação: ter um único maintainer sénior responsável pela primeira revisão
As razões para ter exatamente um maintainer sénior responsável pela primeira revisão são:
- Não há trabalho de revisão duplicado
- O contribuidor e o maintainer trabalham em conjunto no pull request, dando idealmente ao contribuidor a sensação de que não está a fazer isto sozinho
- Não haverá comentários de revisão contraditórios de outros maintainers
Assim que o contribuidor e o maintainer estiverem ambos satisfeitos com o exercício, este deve ser integrado com o seu status definido como wip (trabalho em curso).
Os exercícios com este estado não ficam disponíveis para os estudantes, mas ficarão visíveis para os nossos melhores mentores (assim que implementarmos isto, algures no futuro).
Estes utilizadores com reputação elevada podem então testar o exercício e criar issues ou pull requests para corrigir ou melhorar o exercício.
As principais vantagens desta abordagem são:
- Retira a pressão sobre o par original contribuidor/maintainer de fazer tudo perfeito
- Não dá origem a ciclos enormes de pull requests com várias vozes (que são realmente difíceis de gerir)
Rever pull requests de exercícios de prática
Recomendação: avalia se a alteração pertence realmente ao problem-specifications
Parte do conteúdo de um exercício de prática (como a sua introdução) vem dos seus metadados (partilhados), tal como definidos no repositório problem-specifications.
Ao rever um pull request que altera esse conteúdo, avalia se a alteração também pode beneficiar outras tracks.
Se sim, sugere que o contribuidor abra um pull request para o ficheiro correspondente no repositório problem-specifications.
Recomendações gerais de revisão
Recomendação: um revisor principal por pull request
Todos os pull requests devem ter um revisor principal (seja qual for o maintainer que os assuma).
Os outros maintainers e/ou membros da comunidade devem desempenhar um papel secundário.
Há duas formas principais de alguém com um papel secundário contribuir para uma revisão:
- Rever a ortografia e a gramática, mas apenas depois de o revisor principal ter feito a primeira revisão.
Pode ser frustrante para os contribuidores receberem uma revisão de ortografia e gramática, corrigirem-na e depois aparecer um maintainer a pedir-lhes alterações mais profundas.
Por outras palavras: a revisão de ortografia e gramática é algo que fazes depois de as alterações fundamentais estarem resolvidas (ou, possivelmente, num pull request de seguimento).
- Apontar coisas de uma forma que não exija ação por parte do revisor.
Se comentares coisas em que o revisor principal deve pensar ou que possa ter deixado passar, publica o teu comentário como uma opinião ou sob a forma de pergunta.
Assim fica claro para o contribuidor que não lhe estás a pedir alterações, o que torna tudo menos confuso para ele.
Também reduz a probabilidade de o revisor principal se sentir "desvalorizado".
Recomendação: não comentes coisas que não estão relacionadas
Ao reveres um pull request, comenta apenas coisas diretamente relacionadas com o pull request.
Para tudo o resto, abre uma issue ou cria um pull request separado (de seguimento).
Recomendação: cria ligações para a documentação
Sempre que possível, tenta criar uma ligação para a documentação que explica a razão por que estás a comentar algo.
Isto ajuda bastante a reduzir a probabilidade de as coisas se tornarem motivo de discussão.
Recomendação: pede ajuda a outras equipas
Se quiseres pedir ajuda para rever um pull request, temos duas equipas específicas que podes contactar:
-
@exercism/reviewers: para revisões gerais
-
@exercism/github-actions: para qualquer questão relacionada com as GitHub actions
