Código gerado pelo Stack AI em pull requests

Pull requests grandes são difíceis de examinar e criam 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 do pull request aumenta. Os revisores podem examinar rapidamente o resultado, perder problemas ou procrastinar e deixar a solicitação de pull até ficar obsoleta e desenvolver conflitos de mesclagem.

Pull requests empilhados mantêm grandes alterações de código 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 empilhados com agentes para criar uma funcionalidade em camadas individualmente revisáveis. Por nosso exemplo, consideraremos como adicionar autenticação de usuário a um aplicativo. Usaremos GitHub Copilot CLI e a habilidade de agente gh-stack.

Pré-requisitos

Para usar a gh-stack skill com um agente, primeiro você precisará instalar GitHub CLI e a extensão da CLI gh-stack. 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.
• GitHub Copilot CLI instalado e com sessão iniciada.

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

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

1. Projetar uma pilha antes de gerar código

Um bom stack é como construir uma casa: comece com uma base forte, enquadre as paredes, instale a fiação e, em seguida, finalize o drywall. Cada camada construída, dependendo da camada abaixo. No fim, um revisor deve ser capaz de ler os pull requests de baixo para cima e acompanhar como a funcionalidade vai tomando forma.

• 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 ou trabalhe com Copilot em um plano. De qualquer forma, você define a estrutura da stack.
• Ordene as camadas por dependência. As alterações de base vão na parte inferior. Qualquer coisa que dependa deles fica acima. 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

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 estrutura com a base. Tudo acima depende de acertar essa camada.

• Informe Copilot que você criará uma solicitação de pull empilhada e peça para criar 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 stack 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 você mesmo a alteração gerada 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.

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. Empilhe cada nova camada de código na parte superior

Com a base estabelecida, 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 fará commit do 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 à medida que avança, para que cada ramificação permaneça um diff limpo e autocontido.
• Quando estiver pronto para criar pull requests, peça a Copilot para enviar sua stack ou, se quiser fazer isso por conta própria, use gh stack submit.
• Permita que cada pull request se sustente por si só. 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 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. Deixe Copilot ajudá-lo a verificar cada camada em relação aos seus padrões antes de solicitar revisões.
• Para examinar minuciosamente as alterações geradas por IA, consulte Examinar o código gerado por IA.

5. Solicitar revisões para a stack, 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 para cima 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 analisa os endpoints, e nenhuma das duas percorre toda a funcionalidade.

6. Itere com base no feedback

Os comentários de revisão se aplicam às camadas individualmente, não à funcionalidade como um todo. As pilhas permitem fixar a camada certa no lugar 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 da direita, 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 fazer rebase nos 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 propagar as alterações para o topo da 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 a partir da camada inferior

Uma pilha é mesclada em ordem, começando da camada apontando para o branch principal. 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 a mesclagem automática ou uma fila de mesclagem para que cada ramificação seja mesclada assim que for aprovada e suas verificações passarem. Você não precisa aguardar a pilha inteira de uma vez.

Depois que a camada superior se mesclar, todo o recurso foi integrado. 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

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