Revisando pull requests

Qualquer pessoa pode revisar um pull request da documentação. Visite a seção pull requests no repositório do site Kubernetes para ver os pull requests abertos.

Revisar os pull requests da documentação é uma ótima maneira de se apresentar à comunidade Kubernetes. Isso ajuda você a aprender a base de código e construir a confiança com outros colaboradores.

Antes de revisar, é uma boa ideia:

• Ler o guia de conteúdo e o guia de estilo para que você possa deixar comentários esclarecedores.
• Entender as diferentes funções e responsabilidades na comunidade da documentação do Kubernetes.

Antes de começar

Antes de começar uma revisão:

• Leia o Código de Conduta da CNCF e certifique-se de cumpri-lo o tempo todo.
• Seja educado, atencioso e prestativo.
• Comente os aspectos positivos dos PRs, bem como mudanças.
• Seja empático e cuidadoso, observe como sua avaliação pode ser recebida.
• Assuma boas intenções e faça perguntas esclarecedoras.
• Colaboradores experientes, considere trabalhar em par com os novos colaboradores cujo trabalho requer grandes mudanças.

Processo de revisão

Em geral, revise os pull requests de conteúdo e estilo em inglês. A Figura 1 descreve as etapas para o processo de revisão. Seguem os detalhes para cada etapa.

flowchart LR
    subgraph fourth[Começar revisão]
    direction TB
    S[ ] -.-
    M[adicionar comentários] --> N[revisar mudanças]
    N --> O[novos colaboradores devem
escolher Comment]
    end
    subgraph third[Selecionar PR]
    direction TB
    T[ ] -.-
    J[leia a descrição
e comentários]--> K[visualize as mudanças no ambiente
de pré-visualização do Netlify]
    end
 
  A[Revise a lista de PR abertos]--> B[Filtre os PRs abertos
pela label]
  B --> third --> fourth
     

classDef grey fill:#dddddd,stroke:#ffffff,stroke-width:px,color:#000000, font-size:15px;
classDef white fill:#ffffff,stroke:#000,stroke-width:px,color:#000,font-weight:bold
classDef spacewhite fill:#ffffff,stroke:#fff,stroke-width:0px,color:#000
class A,B,J,K,M,N,O grey
class S,T spacewhite
class third,fourth white

Figura 1. Etapas do processo de revisão.

1. Acesse https://github.com/kubernetes/website/pulls. Você verá uma lista de todas as solicitações de pull requests abertos no site e na documentação do Kubernetes.

2. Filtre os PRs abertos usando um ou todos os labels seguintes:

   • cncf-cla: yes (Recomendado): PRs enviados por colaboradores que não assinaram o CLA não podem ser feito o merge. Consulte Assinar o CLA para obter mais informações.
   • language/pt (Recomendado): Filtro para PRs em português.
   • size/<size>: Filtro para PRs com um determinado tamanho. Se você é novo, comece com PRs menores.

   Além disso, certifique-se que o PR não esteja marcado como work in progress. Os PRs que usam o label work in progress ainda não estão prontos para revisão.

3. Depois de selecionar um PR para revisar, entenda a mudança:

   • Lendo a descrição do PR para entender as alterações feitas e ler quaisquer issues vinculadas
   • Lendo quaisquer comentários de outros revisores
   • Clicando na aba Files changed para ver os arquivos e linhas alteradas
   • Pré-visualizar as alterações ambiente de pré-visualização do Netlify, rolando até a seção PR's build check na parte inferior da aba Conversation. Aqui está uma captura da tela (isso mostra a área de trabalho do site GitHub; se você estiver revisando em um tablet ou smartphone, a interface web do usuário GitHub será um pouco diferente):

     

     Para abrir a visualização, selecione o link Details da linha deploy/netlify na lista de verificações.

4. Vá para a aba Files changed para iniciar sua revisão.

   1. Clique no símbolo + ao lado da linha que você deseja comentar.

   2. Preencha com todos os comentários que você tenha sobre a linha e clique em Add single comment (se você tiver apenas um comentário para fazer) ou Start a review (se você tiver vários comentários para fazer)

   3. Quando terminar, clique em Review changes na parte superior da página. Aqui, você pode adicionar um resumo da sua revisão (e deixar alguns comentários positivos para o colaborador!). Por favor, sempre use o "Comentário"

   • Evite clicar no botão "Request changes" ao concluir sua revisão. Se você quiser bloquear o merge do PR antes que outras alterações sejam realizadas, você pode deixar um comentário "/hold". Mencione por que você está definindo o bloqueio e, opcionalmente, especifique as condições sob as quais o bloqueio pode ser removido por você ou por outros revisores.

   • Evite clicar no botão "Approve" ao concluir sua revisão. Deixar um comentário "/approve" é recomendado na maioria dos casos.

Checklist para revisão

Ao revisar, use como ponto de partida o seguinte.

Linguagem e gramática

• Existe algum erro óbvio na linguagem ou gramática? Existe uma maneira melhor de expressar algo?
  • Concentre-se na linguagem e na gramática nas partes que o autor está mudando na página. A menos que o autor esteja claramente com o objetivo de atualizar a página inteira, ele não tem obrigação de corrigir todos os problemas na página.
  • Quando um PR atualiza uma página existente, você deve se concentrar em revisar as partes que estão sendo atualizadas na página. Esse conteúdo alterado deve ser revisado quanto à correção técnica e editorial. Se você encontrar erros na página que não se relacionam diretamente com o que o autor do PR está tentando resolver, ele deve ser tratado em uma issue separada (primeiro, verifique se não existe uma issue existente sobre isso).
  • Cuidado com os pull requests que movem conteúdo. Se um autor renomear uma página ou combinar duas páginas, nós (Kubernetes SIG Docs) geralmente evitamos pedir a esse autor que corrija todas as questões gramaticais ou ortográficas que poderíamos identificar dentro desse conteúdo movido.
• Existem palavras complicadas ou arcaicas que podem ser substituídas por uma palavra mais simples?
• Existem palavras, termos ou frases em uso que podem ser substituídos por uma alternativa não discriminatória?
• A escolha da palavra e sua capitalização seguem o guia de estilo?
• Existem frases longas que podem ser mais curtas ou menos complexas?
• Existem parágrafos longos que podem funcionar melhor como uma lista ou tabela?

Conteúdo

• Existe conteúdo semelhante em outro lugar no site Kubernetes?
• O conteúdo está excessivamente vinculado a uma documentação externa, de um fornecedor individual ou de um código não aberto?

Website

• Esse PR alterou ou removeu um título da página, slug/alias ou link? Em caso afirmativo, existem links quebrados como resultado deste PR? Existe outra opção, como alterar o título da página sem alterar o slug?
• O PR apresenta uma nova página? Caso afirmativo:
  • A página está usando corretamente o tipo de conteúdo e os códigos relacionados ao Hugo?
  • A página aparece corretamente na navegação da seção (ou em geral)?
  • A página deve aparecer na lista em Documentação/Home?
• As alterações aparecem na visualização do Netlify? Esteja particularmente atento a listas, blocos de código, tabelas, notas e imagens.

Outro

• Cuidado com as edições triviais; se você observar uma mudança que entender ser uma edição trivial, por favor, marque essa política (ainda não há problema em aceitar a alteração se for genuinamente uma melhoria).
• Incentive os autores que estão fazendo correções de espaço em branco a fazê-lo no primeiro commit de seu PR e, em seguida, adicione outras alterações além disso. Isso facilita as revisões e o merge. Cuidado especialmente com uma mudança trivial que aconteça em um único commit, juntamente com uma grande quantidade de limpeza dos espaços em branco (e se você observar isso, incentive o autor a corrigi-lo).

Como revisor, se você identificar pequenos problemas com um PR que não são essenciais para o significado, como erros de digitação ou espaços em branco incorretos, sinalize seus comentários com nit:. Isso permite que o autor saiba que esta parte do seu feedback não é uma crítica.

Se você estiver considerando um pull request e todo o feedback restante estiver marcado como um nit, você pode realizar o merge do PR de qualquer maneira. Nesse caso, muitas vezes é útil abrir uma issue sobre os nits restantes. Considere se você é capaz de atender aos requisitos para marcar esse nova issue como uma Good First Issue; se você puder, esses são uma boa fonte.