Empilhe alterações de código em pull requests

Crie uma sequência de pull requests pequenas e dependentes que podem ser rapidamente revisadas.

Neste artigo

Pull requests grandes são difíceis de revisar e criam gargalos, especialmente quando você gera um alto volume de código em pouco tempo. A qualidade da revisão também se degrada à medida que o tamanho do pull request aumenta. Os revisores podem examinar rapidamente o resultado, deixar de perceber problemas ou procrastinar e deixar o pull request até que fique obsoleto e desenvolva conflitos de mesclagem.

Pull requests empilhados mantêm grandes alterações de código mais fáceis de revisar.

Uma pilha é uma série de solicitações de pull no mesmo repositório em que cada solicitação de pull direciona o branch da solicitação de pull abaixo dela, formando uma cadeia ordenada que cai em um único branch, normalmente seu branch principal. Em vez de uma solicitação de pull grande, você obtém um conjunto de solicitações de pull menores. Como cada solicitação de pull tem sua própria diferença de foco, os colegas de equipe podem examinar e aprovar cada camada de forma independente.

Este tutorial explica como usar pull requests em pilha para criar uma funcionalidade em camadas individualmente revisáveis. Por nosso exemplo, consideraremos como adicionar autenticação de usuário a um aplicativo. Usaremos a gh stack extensão em GitHub CLI.

Pré-requisitos

Para seguir este tutorial, você precisará instalar GitHub CLI e a gh stack extensão. Você precisará do seguinte:

  • GitHub CLI (gh) 2.90.0 ou posterior e Git 2.20 ou posterior.
    • Autentique GitHub CLI com gh auth login.
  • Um GitHub repositório para o qual você pode enviar por push.

No GitHub CLI, instale a extensão gh stack.

gh extension install github/gh-stack

1. Criar uma pilha antes de gerar código

Uma boa stack é como construir uma casa: comece com uma base forte, enquadre as paredes, instale a fiação e, em seguida, conclua o drywall. Cada camada é construída com base na camada abaixo. No final, um revisor deve ser capaz de ler os pull requests de baixo para cima e acompanhar o desenvolvimento da funcionalidade.

  • Divida a funcionalidade em camadas. Cada camada deve ser uma única alteração coerente que pode ser revisada por conta própria.
    • Mantenha cada camada pequena o suficiente para que seu pull request seja uma leitura rápida. Se uma camada parece precisar de uma descrição longa para ser revisada, provavelmente é muito grande.
    • Decida os limites por conta própria. Você define a forma do stack.
  • Ordene as camadas por dependência. As alterações fundamentais vão na parte inferior. Qualquer coisa que dependa deles fica mais alto. Para autenticação, isso pode ser:
    • Camada 1: modelo de dados e migração
    • Camada 2: endpoints CRUD
    • Camada 3: middleware JWT e guards
    • Camada 4: integração e testes de unidade

2. Criar a camada inferior primeiro

Inicie a pilha com a base. Tudo acima depende de acertar essa camada.

  • Crie a pilha e crie a primeira camada com base em seu plano. Crie-o com gh stack init BRANCH-NAME-1, considere usar um prefixo para manter os nomes de ramificação arrumados.
  • Examine a alteração por conta própria antes de seguir em frente. Um erro na camada inferior se propaga para cada ramificação acima dela, portanto, revise-a antes de seguir em frente.

3. Empilhe cada nova camada de código na parte superior

Com a base estabelecida, crie o restante do recurso uma camada de cada vez.

  • Adicione a próxima camada e implemente-a no contexto das camadas abaixo. Adicione um branch no topo da pilha com gh stack add BRANCH-NAME-NEXT e faça commit do trabalho lá.
  • Se uma camada começar a crescer muito grande, considere se ela está fora de seu plano ou se você realmente precisa de duas camadas em vez de uma.
  • Crie novos branchs para cada camada à medida que avança, para que cada branch permaneça um diff limpo e autocontido.
  • Quando estiver pronto para criar pull requests, envie sua stack com gh stack submit.
  • Permita que cada pull request seja independente. Um título focado e uma descrição concisa e significativa da camada geralmente são suficientes.

4. Examine os pull requests por conta própria antes de solicitar uma revisão

Cada camada é pequena, facilitando a auto-revisão também. Faça uma revisão em cada ramificação antes de envolver colegas de equipe. Os revisores devem receber alterações em que você já confia.

  • Execute seus testes, linters e verificação de código em cada branch para verificar cada camada em relação aos seus padrões antes de solicitar revisões.

5. Solicitar revisões para a pilha, começando na parte inferior

Com as camadas criadas, os revisores obtêm pequenos diffs em vez de uma grande parede de código.

  • Se as dependências estiverem fortemente integradas, solicite revisões começando na parte inferior da pilha, para que você possa integrar alterações ao longo da pilha antes das revisões subsequentes.
  • Se você precisar de revisões de pessoas diferentes para diferentes camadas, os revisores poderão trabalhar em paralelo. Uma pessoa pode examinar o modelo de dados enquanto outra revisa os endpoints, e nenhuma das duas precisa revisar todo o recurso.

6. Iterar nos comentários

Os comentários de revisão se aplicam às camadas individualmente, não à funcionalidade inteira. Stacks permitem fixar a camada certa no lugar e levar a alteração para cima.

  • Revise a camada sinalizada por um revisor. Mova para o branch direito, faça a alteração e faça commit dela lá.
  • Mantenha cada correção na camada à qual pertence. Uma alteração feita no branch errado pode confundir e criar erros upstack.
  • Navegue por branches com gh stack down, gh stack upou gh stack checkout BRANCH-NAME. Em seguida, confirme suas alterações, execute gh stack rebase --upstack para rebasear os branches acima e, em seguida gh stack push , para carregar as alterações na pilha.

7. Mesclar a partir da camada inferior

Uma pilha é mesclada em ordem, começando da camada apontando para o branch main. Mesclar camadas de uma só vez, ou uma por uma, e GitHub automaticamente redireciona a próxima camada para apontar para main.

  • Mesclar a pilha um de cada vez trabalhando de baixo para cima ou de qualquer lugar na pilha e todos os branches abaixo do pull request que você mesclar serão mesclados de baixo para cima.
  • A diferença de cada camada permanece exatamente a mesma em relação ao pai, apenas a base muda, facilitando a mesclagem de uma camada de cada vez sem afetar o trabalho ou as revisões em andamento.
  • Use uma fila de mesclagem para que cada ramificação se mescle na ordem depois de aprovada e de passar nas verificações. Você não precisa aguardar a pilha inteira de uma vez.

Depois que a camada superior se mesclar, todo o recurso foi integrada. Cada peça foi revisada de forma mais eficaz como uma pequena e deliberada mudança em vez de um grande pull request.

Leitura adicional