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 ou inferior solicitação de pull tem como destino o tronco da pilha , geralmente o branch padrão do repositório, como main, embora possa ser qualquer branch, como um branch de lançamento.
• 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)

Os branches empilhados formam uma cadeia de dependências, em que cada ramificação se baseia na que está abaixo dela. Alterações fundamentais, como tipos compartilhados e esquema de banco de dados, vão em branches inferiores e o código que depende deles, como rotas de API e componentes de interface do usuário, vão em branches mais altos.

Cada solicitação de pull em uma pilha representa uma alteração discreta e revisável de uma ou mais confirmações. Você pode examinar e iterar em cada solicitação de pull de forma independente, e cada uma delas mostra apenas a diferença para sua camada e as alterações entre seu branch e o branch abaixo dela.

O princípio da chave: se o código em uma camada depender do código em outra, a dependência deverá estar no mesmo branch ou em um menor. 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 solicitação de pull em uma pilha que contém uma alteração focada, os revisores veem uma pequena diferença para cada camada em vez da solicitação de pull grande. Solicitações de pull menores são mais rápidas de revisar, menos propensas a serem desnatados e menos propensas a ficar obsoletas e desenvolver conflitos de mesclagem.

Adequado para desenvolvimento de alto volume

Quando você gera um monte de código de uma só vez, geralmente com agentes de IA, uma pilha fornece a cada alteração um lugar para ir. 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 pilhas permitem que você registre essas dependências explicitamente em vez de combinar 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. A rebasing e a manutenção de branches em sincronização entre solicitações de pull dependentes são tediosas e propensas a erros.
• Regras e CI. As regras de proteção de ramificação e as verificações de CI geralmente só disparam para a solicitação de pull inferior na cadeia, tornando difícil saber o status verdadeiro do restante.
• Revise o contexto. A revisão de 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.

Rebasing

A rebasing é a parte mais complicada de trabalhar com pilhas e GitHub manipula-a automaticamente. Você pode disparar uma rebase em cascata do lado do servidor da solicitação de pull ou executar uma rebase em cascata local com a gh stack extensão em 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 gh stack extensão no GitHub CLI identificador do 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.

GitHub No site

Quando uma solicitação de pull faz parte de uma pilha, você verá:

• Um ícone de pilha na parte superior da solicitação de pull com um número que indica qual camada você está exibindo.
• Um mapa de pilha aparece na caixa de mesclagem. Ele mostra cada solicitação de pull na pilha e seu status e permite que você navegue até qualquer camada com um clique. O tronco (branch base padrão) está na parte inferior, com cada solicitação de pull na pilha direcionando o branch da solicitação de pull abaixo dele.

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 stack objeto em pull_request cargas de eventos, para que sua automação possa responder quando uma solicitação de pull ingressar, se mover para dentro ou sair de uma pilha.
• A API REST lê a associação de pilha de uma solicitação pull e fornece pontos de extremidade para listar, criar, estender e dissolver pilhas.
• A API do GraphQL expõe campos somente stack leitura em uma solicitação de pull para consultar a pilha e a posição da solicitação de pull nela.

Regras, CI e mesclagem

Regras e imposiçã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.

• Regras de proteção de ramificação, como aprovações CODEOWNER, são impostas em cada solicitação de pull na pilha, até mesmo solicitações de pull de pilha intermediária que não direcionam diretamente seu 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 à mesma barra de qualidade antes de mesclar.

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.

• Mesclar toda a pilha de uma só vez mesclando a solicitação de pull superior. Cada solicitação de pull abaixo vem com ela.
• Mesclar parte da pilha mesclando uma solicitação de pull de pilha intermediária. 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 pilhas dão suporte a métodos de mesclagem, squash e rebase, além de estarem cientes da fila de mesclagem. O histórico de confirmação resultante é o mesmo que mesclar cada solicitação de pull individualmente, começando na parte inferior.

Próximas Etapas 

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