Distribuir solicitações de pull empilhadas para sua organização

As solicitações de pull empilhadas permitem que os desenvolvedores dividam grandes alterações em uma cadeia de solicitações de pull pequenas e focadas que se baseiam umas nas outras, tornando cada camada mais fácil de examinar, mesclar e enviar. As solicitações de pull empilhadas dão aos desenvolvedores a flexibilidade para concluir um trabalho e ir direto para o próximo sem esperar que as revisões cheguem. Isso é mais importante quando o trabalho naturalmente depende do que veio antes dele, o que é comum quando uma equipe está trabalhando em um grande lançamento e cada alteração se baseia no último.

Este tutorial orienta você na preparação de sua organização para solicitações de pull empilhadas: revisão de considerações de distribuição, compreensão de como as regras de proteção de branch e CI funcionam com pilhas e introdução às suas equipes. Para obter uma compreensão fundamental das solicitações de pull empilhadas, consulte Sobre solicitações de pull empilhadas.

Pré-requisitos

Se sua equipe já estiver usando solicitações de pull, você estará configurado para usar solicitações de pull empilhadas. Todo o resto neste tutorial é opcional, mas pressupõe que sua organização tenha:

• GitHub CLI, com a gh-stack extensão instalada. A extensão da CLI é a maneira mais abrangente de criar e gerenciar pilhas.
• Regras de proteção de ramificação configuradas para o branch padrão.
• GitHub Actions fluxos de trabalho executados em solicitações de pull direcionadas ao branch padrão.

Copilot não é necessário usar solicitações de pull empilhadas, mas é incentivado para equipes que desejam empilhar alterações geradas por IA. As solicitações de pull empilhadas também funcionam com outros agentes de codificação de IA, como Claude Code e Codex, usando a habilidade de agente fornecida. Consulte Código gerado por IA do Stack em solicitações de pull.

1. Revise as considerações de distribuição

Antes de introduzir solicitações de pull empilhadas para suas equipes, examine as considerações a seguir para que todos saibam o que esperar.

As pilhas devem ser lineares e não podem incluir bifurcações

Cada solicitação de pull em uma pilha deve fazer parte do mesmo repositório e criar uma única cadeia linear de branches. Não há suporte para pilhas com estruturas de ramificação ou solicitações de pull de bifurcações. Se suas equipes dependerem de bifurcações para contribuições, planeje manter essas contribuições fora das pilhas por enquanto.

Reordenar uma pilha requer GitHub CLI

Se sua equipe precisar reordenar as solicitações de pull em uma pilha, ela precisará ser usada gh stack modify na gh stackGitHub CLI extensão. Não há como reordenar uma pilha do GitHub site. As equipes que não usam a CLI localmente devem planejar sua ordem de pilha cuidadosamente antecipadamente ou instalar a extensão para essa tarefa.

Uma pilha concluída não pode ser estendida

Depois que cada solicitação de pull em uma pilha for mesclada, essa pilha será fechada. Se uma equipe adicionar novos branches na parte superior e for executada gh stack submit, a CLI iniciará uma nova pilha com o mesmo branch base. As equipes que desejam continuar trabalhando em uma pilha devem planejar manter a pilha aberta até que todo o trabalho seja concluído.

2. Entenda como as regras de proteção de branch e a CI funcionam com pilhas

As solicitações de pull empilhadas são projetadas para impor suas regras existentes da mesma maneira que qualquer outra solicitação de pull, mas vale a pena entender como, uma vez que cada solicitação de pull em uma pilha é avaliada um pouco diferente do esperado.

Cada solicitação de pull em uma pilha, não apenas na parte inferior, é avaliada na base da pilha (normalmente main), em vez de no branch direcionado diretamente. Isso significa que:

• Revisões necessárias, verificações de status necessárias e CODEOWNERS são todas impostas no branch base da pilha para cada solicitação de pull na pilha.
• Um GitHub Actions fluxo de trabalho que dispara em pull_request eventos main direcionados é executado para cada solicitação de pull na pilha, de modo que sua configuração de CI existente não precisa ser alterada.
• Os metadados de pilha estão disponíveis em expressões de fluxo de trabalho por meio github.event.pull_request.stackde, se você quiser personalizar o comportamento do fluxo de trabalho especificamente para solicitações de pull empilhadas. Como um fluxo de trabalho é executado uma vez por solicitação de pull em uma pilha, as equipes podem usar esses metadados para ignorar trabalhos caros em execuções redundantes e reduzir o uso de CI. Para obter detalhes, consulte Otimizando a CI para solicitações de pull empilhadas.

Opcionalmente, você pode ver isso em ação abrindo uma pequena pilha de teste em um repositório com seus conjuntos de regras padrão e verificações necessárias em vigor e confirmando que:

1. Revisões e verificações de status são necessárias em cada solicitação de pull na pilha, não apenas na parte inferior.
2. Os fluxos de trabalho de CI são executados em cada solicitação de pull na pilha.
3. A mesclagem é bloqueada até que a solicitação de pull na pilha que você deseja mesclar e tudo abaixo dela atenda às suas necessidades.

Para obter a lista completa de regras e requisitos, consulte Solicitações de pull empilhadas.

3. Introdução às suas equipes

Depois de examinar as considerações de distribuição e entender como suas regras e CI funcionam com pilhas, aponte suas equipes para Solicitações de pull empilhadas 🥞, o que reúne tudo o que eles precisam para começar a criar, revisar e mesclar solicitações de pull empilhadas.

4. Atualizar suas ferramentas programáticas

À medida que sua organização adota solicitações de pull empilhadas, examine todas as ferramentas internas, bots ou dashboards que criam, mesclam ou rastreiam solicitações de pull programaticamente e atualize-as para levar em conta as pilhas.

Você também pode querer acompanhar a atividade de pilha programaticamente, por exemplo, entre dashboards, bots ou ferramentas internas.

• API REST: cada solicitação de pull retornada pela API inclui um stack objeto quando pertence a uma pilha, mostrando o número, o tamanho da pilha, a posição da solicitação de pull dentro dela e o branch base da pilha. Uma API dedicada do Stacks (GET /repos/{owner}/{repo}/stacks) também lista todas as pilhas em um repositório ou a pilha específica que contém uma determinada solicitação de pull. Consulte Solicitações de pull empilhadas nas APIs REST e GraphQL.
• Webhooks: o conteúdo do pull_request webhook inclui o mesmo stack objeto sempre que uma solicitação de pull pertence a uma pilha. Uma ação dedicada stacked é acionada quando uma solicitação de pull é adicionada pela primeira vez a uma pilha, para que você possa reagir no momento em que uma pilha se forma.

Em ambos os casos, o stack campo é null para solicitações de pull autônomas, portanto, as integrações existentes que não esperam pilhas continuam funcionando inalteradas.