Sobre solicitações de pull empilhadas

Sobre solicitações de pull empilhadas

As solicitações de pull empilhadas são duas ou mais solicitações de pull no mesmo repositório, em que:

• A primeira pull request, ou a de baixo, tem como alvo a branch principal da pilha — geralmente a branch padrão do seu repositório, como main, embora possa ser qualquer branch, como uma branch de release.
• Cada solicitação de pull subsequente tem como destino o branch da solicitação de pull abaixo dela.

   ┌── feat/frontend     → PR #3 (base: feat/api-endpoints)  ← top
  ┌── feat/api-endpoints → PR #2 (base: feat/auth-layer)
 ┌── feat/auth-layer     → PR #1 (base: main)               ← bottom
main (default base branch)

As ramificações empilhadas formam uma cadeia de dependências, na qual cada ramificação se baseia na ramificação abaixo. Alterações fundamentais, como tipos compartilhados e a estrutura do banco de dados, vão em branches de nível mais baixo, e o código que depende delas, como rotas de API e componentes da interface do usuário, vai em branches de nível mais alto.

Cada pull request em uma pilha representa uma alteração distinta, que pode ser revisada, de um ou mais commits. Você pode revisar e fazer iterações em cada pull request de forma independente, e cada um mostra apenas o diff da sua camada e as alterações entre seu branch e o branch imediatamente abaixo.

O princípio fundamental: se o código em uma camada depende de código em outra, a dependência deve estar no mesmo branch ou em um inferior. Crie uma nova ramificação quando você iniciar uma preocupação diferente que dependa do que você criou até agora. Por exemplo, quando você alterna do back-end para o trabalho de front-end, passa da lógica principal para os testes ou quando o branch atual já é grande o suficiente para revisão.

Por que usar GitHub solicitações de pull empilhadas

Concluir uma alteração e ir direto para a próxima

As solicitações de pull empilhadas permitem que você abra uma nova solicitação de pull em cima de uma que ainda esteja aberta. Durante um projeto grande, sua próxima alteração pode depender do trabalho que ainda não foi mesclado. Em vez de esperar que ele se mescle, com uma pilha, você pode continuar criando.

Com cada pull request em uma pilha contendo uma alteração específica, os revisores veem um diff pequeno para cada camada, em vez de um pull request grande. Pull requests menores são mais rápidos de revisar, têm menos probabilidade de serem revisados superficialmente e menos probabilidade de ficarem desatualizados e gerarem conflitos de mesclagem.

Adequado para desenvolvimento de alto volume

Quando você gera muito código de uma só vez, muitas vezes com agentes de IA, uma stack dá a cada alteração um lugar específico. Um agente conclui uma tarefa e inicia a próxima tarefa que se baseia nela. Essa sequência é mapeada diretamente para uma pilha: uma solicitação de pull por tarefa, cada uma com base na abaixo. As stacks permitem que você registre essas dependências explicitamente, em vez de agrupar alterações não relacionadas em um único branch.

Vantagens de usar solicitações de pull empilhadas no GitHub

Sem solicitações de pull empilhadas, dividir uma grande alteração em solicitações de pull menores e dependentes cria um trabalho extra:

• Gerenciamento de ramificação. Fazer rebase e manter branches sincronizadas em pull requests dependentes é trabalhoso e propenso a erros.
• Regras e CI. As regras de proteção de branch e as checagens de CI geralmente só são acionadas para o pull request na base da cadeia, o que dificulta saber o status real dos demais.
• Revise o contexto. Revisar uma única alteração fora do contexto do restante da pilha pode reduzir a qualidade da revisão.

As solicitações de pull empilhadas resolvem esses problemas tratando a cadeia de solicitações de pull como uma unidade conectada, mantendo cada camada pequena e focada.

Rebase

Rebase é a parte mais complicada de trabalhar com stacks, e GitHub cuida disso automaticamente. Você pode acionar um rebase em cascata no servidor a partir do pull request ou executar um rebase em cascata local com a extensão gh stack no GitHub CLI. Quando você mescla uma solicitação de pull na parte inferior da pilha, as ramificações restantes são rebasadas automaticamente para que a próxima solicitação de pull seja direcionada ao branch base padrão.

Onde você pode usar solicitações de pull empilhadas

As solicitações de pull empilhadas estão disponíveis no seguinte:

• GitHub CLI
• Site do GitHub
• GitHub Mobile
• Suporte programático por meio de Webhooks, API REST e GraphQL
• Para agentes, por meio da gh-stack habilidade

No GitHub CLI

A extensão gh stack em GitHub CLI gerencia o fluxo de trabalho de desenvolvimento local. Você pode criar e acompanhar branches na ordem de dependência correta, manter branches rebased, enviar branches por push, criar e vincular solicitações de pull e navegar entre camadas. Consulte Comandos da CLI de solicitações de pull empilhadas.

No site GitHub

Quando um pull request faz parte de uma pilha de pull requests, você verá:

• Um ícone de pilha no topo do pull request, com um número que indica qual camada você está visualizando.
• Um mapa da pilha aparece na caixa de mesclagem. Ele mostra cada pull request da pilha e seu status, e permite que você navegue até qualquer nível com um clique. A trunk (branch base padrão) fica na parte inferior, com cada pull request da pilha tendo como destino a branch da pull request logo abaixo.

Suporte programático por meio de Webhooks, API REST e GraphQL

As solicitações de pull empilhadas estão disponíveis programaticamente, para que você possa integrá-las às suas próprias ferramentas, automação e dashboards:

• Os webhooks incluem um objeto stack nas cargas de eventos pull_request, para que sua automação possa responder quando um pull request entra, é movido dentro ou sai de uma pilha.
• A API REST lê o pertencimento de um pull request a uma pilha e fornece endpoints para listar, criar, estender e desfazer pilhas.
• A API do GraphQL expõe campos stack somente leitura em um pull request para consultar a pilha e a posição do pull request nela.

Regras, CI e mesclagem

Regras e aplicação de CI

Solicitações de pull empilhadas dão suporte GitHub Actions a fluxos de trabalho.

Os requisitos de mesclagem para qualquer solicitação de pull na pilha são determinados pelo branch base da solicitação de pull inferior, normalmente main.

• As regras de proteção de branch, como aprovações de CODEOWNER, são aplicadas a cada pull request da stack, inclusive aos pull requests intermediários da stack que não têm como destino direto o branch padrão.
• As verificações de CI disparadas por solicitações de pull na ramificação padrão são executadas para todas as solicitações de pull na pilha, não apenas na parte inferior.

Isso garante que cada camada da pilha atenda ao mesmo padrão de qualidade antes de ser integrada.

Mesclagem

Você pode mesclar toda a pilha, uma única solicitação de pull ou uma parte da pilha que abrange várias solicitações de pull. A pilha inteira não precisa ser mesclada de uma só vez, mas as solicitações de pull devem ser mescladas de baixo para cima.

• Mescle toda a pilha de uma só vez ao mesclar o pull request do topo. Cada pull request abaixo vem com isso.
• Mescle parte da pilha ao mesclar um pull request no meio da pilha. As solicitações de pull abaixo dele também se mesclam e as solicitações de pull acima permanecem abertas e redirecionam automaticamente o branch base da pilha.

As stacks oferecem suporte aos métodos de merge merge commit, squash e merge com rebase, além de serem compatíveis com a fila de merge. O histórico de commits resultante é o mesmo de mesclar cada pull request individualmente, de baixo para cima.

Próximas Etapas 

• Início Rápido para solicitações de pull empilhadas
• Distribuir solicitações de pull empilhadas para sua organização