Guia de pull request para mantenedores

Como mantenedor, revisar pull requests é algo que você vai fazer com bastante frequência. Este documento reúne algumas diretrizes de revisão de pull requests específicas do Exercism.

Revisando pull requests de exercícios

Revisar um pull request de um exercício de conceito ou de um exercício de prática pode ser assustador, dadas as muitas regras que envolvem esses tipos de exercício. Por isso, uma primeira revisão feita por um mantenedor costuma levar de duas a três horas e render dezenas de comentários. Nos exercícios de conceito, também existem arquivos com objetivos e conteúdos parecidos (por exemplo, o exercício e a introdução do conceito), e focar em deixar um deles perfeito antes de se espalhar demais é essencial.

Para ajudar a agilizar esse fluxo de trabalho, desenvolvemos as seguintes recomendações.

Recomendação: tenha um mantenedor sênior responsável pela primeira revisão

Os motivos para que exatamente um mantenedor sênior seja responsável pela primeira revisão são:

  • Não existe trabalho de revisão duplicado
  • O contribuidor e o mantenedor vão trabalhar em dupla no pull request, o que, espera-se, dá ao contribuidor a sensação de que não está fazendo isso sozinho
  • Não haverá comentários de revisão contraditórios de outros mantenedores

Recomendação: faça o merge com o status wip

Quando o contribuidor e o mantenedor estiverem satisfeitos com o exercício, o exercício deve receber merge com seu status definido como wip (work-in-progress). Exercícios com esse status não ficarão disponíveis para os estudantes, mas poderão ser vistos pelos nossos melhores mentores (quando implementarmos isso em algum momento no futuro). Esses usuários com alta reputação poderão então testar o exercício e abrir issues ou pull requests para corrigir ou melhorar o exercício.

Os principais benefícios dessa abordagem são:

  • Ela tira da dupla original de contribuidor e mantenedor o peso de ter que deixar tudo perfeito
  • Ela não gera ciclos gigantes de pull requests com várias vozes (que são muito difíceis de gerenciar)

Revisando pull requests de exercícios de prática

Recomendação: considere se a mudança realmente pertence ao problems-specifications

Parte do conteúdo de um exercício de prática (como sua introdução) vem de seus metadados (compartilhados), conforme definido no repositório problems-specifications. Ao revisar um pull request que altera esse tipo de conteúdo, considere se a mudança também poderia beneficiar outras trilhas. Se sim, sugira que o contribuidor abra um pull request para o arquivo correspondente no repositório problems-specifications.

Recomendações gerais de revisão

Recomendação: um revisor principal por pull request

Todos os pull requests devem ter um revisor principal (o mantenedor que assumir a tarefa). Os demais mantenedores e/ou membros da comunidade devem atuar em um papel secundário.

Há duas maneiras principais de alguém em um papel secundário contribuir com uma revisão:

  • Revisar ortografia e gramática, mas só depois que a primeira revisão do revisor principal tiver acontecido. Pode ser frustrante para os contribuidores receber uma revisão de ortografia e gramática, corrigir tudo e depois um mantenedor aparecer pedindo mudanças mais fundamentais. Em outras palavras: a revisão de ortografia e gramática é algo que você faz depois que as mudanças fundamentais forem resolvidas (ou, quem sabe, em um pull request seguinte).
  • Apontar coisas de uma forma não acionável para o revisor. Se você comentar sobre coisas que o revisor principal deveria considerar ou que talvez tenham passado batido, publique seu comentário como uma opinião ou formulado como uma pergunta. Isso deixa claro para o contribuidor que você não está pedindo que ele faça mudanças, o que torna tudo menos confuso para ele. Também reduz a chance de o revisor principal se sentir "desautorizado".

Recomendação: não comente sobre coisas não relacionadas

Ao revisar um pull request, comente apenas sobre coisas diretamente relacionadas ao pull request. Para qualquer outra coisa, abra uma issue ou crie um pull request separado (de acompanhamento).

Sempre que possível, tente incluir um link para a documentação que explica o motivo pelo qual você está comentando algo. Isso ajuda muito a reduzir a chance de as coisas virarem discussão.

Recomendação: peça ajuda a outras equipes

Se você quiser pedir ajuda para revisar um pull request, temos duas equipes específicas que você pode acionar:

  • @exercism/reviewers: para revisões gerais
  • @exercism/github-actions: para qualquer dúvida sobre GitHub Actions