Solicitações de pull grandes são difíceis de examinar e criar gargalos, especialmente quando a IA ajuda você a gerar um alto volume de código em um curto espaço de tempo. A qualidade da revisão também se degrada à medida que o tamanho da solicitação de pull aumenta. Os revisores podem deslizar o resultado, perder problemas ou procrastinar e deixar a solicitação de pull até ficar obsoleta e desenvolver conflitos de mesclagem.

As solicitações de pull empilhadas mantêm as alterações de código grandes revisáveis.

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 solicitações de pull empilhadas com agentes para criar um recurso em camadas individualmente revisáveis. Por nosso exemplo, consideraremos como adicionar autenticação de usuário a um aplicativo. Usaremos CLI do GitHub Copilot e a habilidade do gh-stack agente.

Pré-requisitos

Para usar a gh-stack habilidade com um agente, primeiro você precisará instalar GitHub CLI e a extensão da gh-stack CLI. Você precisará do seguinte:

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

In GitHub CLI, instale a extensão e a gh-stack habilidade.

gh extension install github/gh-stack
gh skill install github/gh-stack

1. Criar uma pilha antes de gerar código

Uma boa pilha é como construir uma casa, começar com uma base forte, enquadrar as paredes, instalar fiação e, em seguida, terminar o drywall. Cada camada criada, dependendo da abaixo. No final, um revisor deve ser capaz de ler as solicitações de pull de baixo para cima e seguir o recurso se unindo.

• Divida o recurso 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 sua solicitação de pull seja uma leitura rápida. Se uma camada parece precisar de uma descrição longa para revisar, provavelmente é muito grande.
  • Decida os limites por conta própria ou trabalhe com Copilot um plano. De qualquer forma, você tem a forma da pilha.
• Ordene as camadas por dependência. As alterações fundamentais vão na parte inferior. Qualquer coisa que dependa deles vai mais alto. Para autenticação, isso pode ser:
  • Camada 1: modelo de dados e migração
  • Camada 2: pontos de extremidade CRUD
  • Camada 3: middleware JWT e guardas
  • Camada 4: integração e testes de unidade

Prompts de exemplo

• Propose a layered approach to add user authentication to this app. Order the layers by dependency, keeping each layer independently reviewable.
• Review my planned layers and flag any that are too large or that depend on a branch above them.

2. Criar a camada inferior primeiro

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

• Informe Copilot que você criará uma solicitação de pull empilhada e solicitará que ela crie a primeira camada com base em seu plano. O agente usa a gh-stack habilidade para criar o primeiro branch da pilha.
• Se você preferir criar a pilha por conta própria, crie-a diretamente com gh stack init, usando um prefixo para manter os nomes de ramificação arrumados, por exemplo, gh stack init BRANCH-NAME-1.
• Examine a alteração gerada antes de seguir em frente. Um erro na camada inferior se propaga para cada branch acima dele, portanto, dê-lhe uma revisão antes de seguir em frente.

Prompts de exemplo

• Start the pr-stack and build only the first layer: the user data model and migration.
• Conduct a review of the generated code and confirm this branch contains only the data model and migration, and nothing that belongs in a later layer.

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

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

• Peça Copilot para adicionar a próxima camada e implementá-la no contexto das camadas abaixo. O agente adicionará um branch à parte superior da pilha e confirmará o trabalho lá.
• Se você quiser adicionar um branch por conta própria, use gh stack add BRANCH-NAME-NEXT.
• 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 branches para cada camada conforme o uso, para que cada ramificação permaneça uma diferença limpa e autocontida.
• Quando estiver pronto para criar solicitações de pull, peça Copilot para enviar sua pilha ou, se você quiser fazer isso por conta própria, use gh stack submit.
• Permita que cada solicitação de pull fique por conta própria. Um título focado e uma descrição concisa e significativa da camada geralmente são suficientes.

Prompts de exemplo

• Add the next layer in a new branch on top: the CRUD endpoints that use the user model from the branch below.
• This branch is getting large. Suggest how it could be split into two independently reviewable layers.

4. Examine as solicitações de pull por conta própria antes de solicitar uma revisão

Cada camada é pequena, facilitando a auto-revisão também. Faça uma passagem 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. Deixe ajudá-lo Copilot a verificar cada camada em relação aos seus padrões antes de solicitar revisões.
• Para obter as técnicas para examinar as alterações geradas por IA de forma completa, consulte Examinar o código gerado por IA.

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

Com as camadas criadas, os revisores obtêm pequenas diferenças 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 na pilha antes das revisões subsequentes.
• Se você precisar de revisões de pessoas separadas para diferentes camadas, os revisores poderão trabalhar em paralelo. Uma pessoa pode examinar o modelo de dados enquanto outra analisa os pontos de extremidade e não percorre todo o recurso.

6. Iterar nos comentários

Os comentários de revisão são baseados em camadas individualmente, não em todo o recurso. As pilhas permitem corrigir a camada certa no local e levar a alteração para cima.

• Peça Copilot para revisar a camada que um revisor sinalizou. O agente move-se para o branch direito, faz a alteração e confirma-a lá. Em seguida, ele rebaseia as camadas acima para que elas peguem a correção.
• Mantenha cada correção na camada à qual pertence. Uma alteração feita no branch errado pode confundir e criar erros upstack.
• À medida que você faz correções, peça Copilot para basear novamente os branches acima e propagar alterações.
• Se você quiser percorrer a pilha por conta própria, navegue pelos branches com gh stack down, gh stack upou gh stack checkout BRANCH-NAME. Em seguida, confirme suas alterações e execute gh stack rebase --upstack para carregar as alterações na pilha.

Prompts de exemplo

• A reviewer flagged that the auth service doesn't handle expired tokens. Fix that on BRANCH-NAME and test the changes.
• I've rebased the layers above onto this fix. Check that the branch with endpoints still works with the change and flag anything that needs updating.

7. Mesclar da camada inferior

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

• Mesclar a pilha um de cada vez trabalhando de baixo para cima ou de qualquer lugar na pilha e todos os branches abaixo da solicitação de pull 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 as alterações de base, facilitando a mesclagem de uma camada de cada vez sem afetar o trabalho ou as revisões em andamento.
• Use a mesclagem automática ou uma fila de mesclagem para que cada camada seja mesclada assim que for aprovada e suas verificações passarem. Você não precisa esperar em toda a pilha de uma vez.

Depois que a camada superior se mesclar, todo o recurso será desembarcado. Cada peça foi revisada de forma mais eficaz como uma pequena e deliberada mudança em vez de uma grande solicitação de pull.

Leitura adicional

• Examinar o código gerado por IA
• Gerenciando solicitações de pull empilhadas