Ler em inglês

Compartilhar via


Processo de revisão das solicitações de pull para repositórios de documentos do .NET

Alguns repositórios, incluindo os repositórios do .NET, não têm o web hook "PR Merger" habilitado, que mescla automaticamente as PRs secundárias. Este artigo descreve o processo de revisão de PR para esses repositórios. O processo de revisão de PR foi criado com estas metas:

  • Publicar conteúdo de alta qualidade da equipe, membros da equipe de produto e membros da comunidade.
  • Fornecer comentários oportunos e práticos para autores de maneira consistente.
  • Facilitar a discussão entre autores e revisores.

Os processos continuam a evoluir conforme as equipes inovam e a plataforma amadurece.

Revisores

Um dos membros da equipe de conteúdo examina cada PR. Os membros da equipe de conteúdo podem solicitar uma revisão de membros específicos da equipe de produto para verificar a exatidão técnica. A equipe de conteúdo usa recursos de propriedade de código do GitHub para solicitar automaticamente revisões de membros da equipe de conteúdo. Como parte desse processo, um revisor pode marcar outros membros da equipe para revisar PRs internos. Os membros da equipe veem as revisões solicitadas de membros da equipe e membros da comunidade na mesma fila.

Membros da comunidade podem revisar PRs e fazer comentários. No entanto, pelo menos um membro da equipe de conteúdo principal deve aprovar qualquer PR antes da mesclagem.

Plano de revisão

As revisões seguem um dos três caminhos com base no PR:

  • PRs pequenos - PRs pequenos são uma única correção de bug: erros de ortografia, links desfeitos, pequenas alterações de código ou alterações semelhantes.
  • Grandes contribuições - as grandes contribuições são edições significativas em um artigo existente, em novos artigos ou edições em vários artigos.
  • Trabalho em andamento – os autores podem criar uma PR que está marcada como ainda não pronta para revisão abrindo uma solicitação de pull de rascunho.

O processamento usado pelo bot de CLA (Contrato de Licença do Colaborador) é uma boa diretriz para a distinção entre contribuições "pequenas" e "grandes". PRs que não exigem que o CLA seja assinado provavelmente são "pequenos". PRs que exigem o CLA provavelmente são "grandes".

PRs pequenos

As alterações em PRs pequenas são examinadas para fins de precisão e verificadas usando o build do site de análise. Como são pequenos, esses PRs não disparam uma revisão do artigo inteiro.

Os revisores podem notar outras pequenas alterações que melhorariam um artigo. Se essas alterações também forem pequenas, sugira-as em comentários. Se as alterações sugeridas dispararem uma revisão maior, abra um problema e resolva-o mais tarde.

Alterações maiores

PRs maiores passam por uma revisão mais completa. Tudo isto é verificado:

  • O código de exemplo deve estar incluído no PR, na origem e como um arquivo zip para download.
  • O código de exemplo é compilado e executado corretamente.
  • O artigo descreve claramente as metas para o leitor, e essas metas são cumpridas.
  • O artigo atende às diretrizes de estilo e gramática e segue nossos princípios de voz e tom.
  • Todos os links devem ser resolvidos corretamente.

Os membros da equipe de conteúdo examinarão a PR e enviarão a revisão com comentários. Se somente pequenas alterações forem solicitadas, os membros da equipe "aprovam" o PR com os comentários. O autor pode resolver os comentários e mesclar o PR. A maioria das revisões solicita alterações e, quando essas alterações são feitas, o revisor faz outra revisão.

Se as edições exigirem uma revisão técnica, o revisor da equipe de conteúdo solicitará uma revisão do membro da equipe de produto apropriado.

Examinar as solicitações de pull de rascunho

Talvez você queira receber feedback antecipado no processo. Abra uma PR de rascunho e adicione um comentário solicitando uma análise antecipada. Essas revisões antecipadas enfocam a estrutura do artigo: a estrutura de tópicos, o conteúdo geral e os exemplos. Elas não incluem uma verificação completa de gramática e links corretos.

Explicar sugestões

O GitHub permite que você insira comentários em blocos de acentos graves triplos do tipo suggestion, os quais são exibidos como uma comparação e podem ser mesclados clicando em um botão. Em linhas curtas, o GitHub faz um bom trabalho ao realçar as alterações. Em linhas mais longas, como um parágrafo longo em uma linha de texto, o GitHub não realça as alterações. Ao inserir uma sugestão para uma linha longa, observe se as suas alterações estão claramente realçadas. Se as alterações não estiverem realçadas, inclua comentários fora do bloco de sugestões explicando o que você alterou. Sem uma explicação, muitas vezes é demorado para os revisores subsequentes ou o criador da PR descobrir quais são as alterações.

Responder às revisões

O autor atualiza a PR para responder aos comentários. Se o autor não concordar com o comentário ou abordar o comentário em uma PR diferente, ele adicionará um comentário explicando a alteração.

O autor faz uma menção com @ ao revisor original em um comentário para solicitar uma nova revisão.

Tempos de resposta esperados

Geralmente, os membros da equipe de conteúdo revisam PRs novo em dois dias úteis.

Depois que uma revisão for enviada, os autores devem tentar responder aos comentários em uma semana ou menos. Os voluntários podem não conseguir atender a essas expectativas devido a outros compromissos. Nesses casos, os membros da equipe perguntarão se o autor da comunidade atualizará o PR. Caso contrário, o membro da equipe atualizará e mesclará o PR para ele.