Alterações de código de pilha em solicitações de pull

Observação

Esse recurso está em versão prévia pública e está sujeito a alterações.

Solicitações de pull grandes são difíceis de examinar e criar 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 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 para criar um recurso 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.
- Autenticar GitHub CLI com gh auth login.
Um GitHub repositório para o qual você pode enviar por push.

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

gh extension install github/gh-stack

1. Criar uma pilha antes de gerar código

Uma boa pilha é como construir uma casa: comece com uma base forte, enquadrem as paredes, instale a fiação e, em seguida, conclua 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 desenvolvimento do recurso.

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. 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

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 branch acima dele, portanto, dê-lhe uma revisão antes de seguir em frente.

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.

Adicione a próxima camada e implemente-a no contexto das camadas abaixo. Adicione um branch à parte superior da pilha gh stack add BRANCH-NAME-NEXT e confirme o 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 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, envie sua pilha com 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.

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 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 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 revisa os pontos de extremidade e nem trabalha com a revisão de 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.

Revise a camada sinalizada por um revisor. Mova para o branch direito, faça a alteração e confirme-a 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 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 uma fila de mesclagem para que cada camada se mescle na ordem depois de aprovada e suas verificações passem. 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.