TL;DR Como usar IA e stacked PRs para facilitar a vida do seu time na revisão de um PR grande.
Publicado originalmente em antoniel.sh.
O problema
Você abre um PR e percebe que ele tem algo em torno de 10 mil linhas de mudança. Nesse ponto, o problema não é só o tamanho do código. É a experiência de review. Um PR desse tamanho é difícil de entender, fácil de adiar e fácil de revisar mal.
Em retrospecto, isso deveria ter sido uma stack desde o começo.
Stacked PRs
A primeira explicação clara de stacked PRs que vi foi na talk do Tomas Reimers na GitKon 2022 sobre o tema: Stacked Pull Requests | GitKon 2022 | Tomas Reimers, Graphite. A ideia é simples: em vez de um PR gigante, você cria uma sequência de PRs menores, em que cada um se apoia no anterior.
Graphite é uma das ferramentas associadas a esse workflow, mas a ideia principal independe da ferramenta. Uma stack é mais fácil de revisar porque cada PR carrega uma parte da história.
| Um PR gigante | Stacked PRs |
|---|---|
| Um review com contexto demais | Vários reviews com limites claros |
| Refactors e feature work misturados | Cada PR carrega uma parte da mudança |
| Fácil de adiar ou revisar por cima | Mais fácil de revisar em ordem |
Um guia prático
Idealmente, você planeja a stack desde o começo e agrupa as mudanças por entrega. Mas às vezes você só percebe o problema quando o PR já está grande demais. Nesse caso, a IA pode ajudar a quebrar a branch em uma stack revisável com muito menos trabalho manual.
- Peça para a IA dividir a branch em stacked PRs.
- Valide que a branch final da stack preserva a mudança original.
- Peça para a IA gerar o fluxo de
ghpara abrir os PRs em ordem.
Usando IA para criar a stack
Esse é um daqueles casos em que o prompt pode continuar simples.
My branch against
mainhas a huge diff. Split it into stacked PRs. Create the branches locally and I will push them.
O resultado pode voltar em um formato como este:
I split the branch into 5 stacked PRs.
Merge order:
1. stacked (foundation)
2. 02-api-cleanup (base: stacked)
3. 03-shared-types (base: 02-api-cleanup)
4. 04-backend-flow (base: 03-shared-types)
5. 05-frontend-flow (base: 04-backend-flow)
Como validar que nada se perdeu
A verificação que importa
Quando a IA propõe a stack, o próximo passo é validar.
I need a quick way to compare the original branch with the final stacked branch and verify that nothing important was lost.
Isso te dá um comando como este:
git --no-pager diff main <original-branch> --shortstat && echo "" && git --no-pager diff main <last-stacked-branch> --shortstat
Se os dois resumos forem efetivamente iguais, a branch final da stack preserva a mudança original. Pequenas diferenças de formatação são aceitáveis; o formato geral do diff deve continuar o mesmo.
61 files changed, 10234 insertions(+), 487 deletions(-)
61 files changed, 10240 insertions(+), 492 deletions(-)
Automatizando a abertura dos PRs com gh CLI
Depois que o diff confere, o problema restante é operacional: abrir cada PR e configurar a base correta.
O fluxo com gh
I already have the stacked branches. Give me a
ghCLI flow to open the PRs in order and set each base branch correctly.
Faça push de todas as branches primeiro e depois use o fluxo gerado com gh:
PR1=$(gh pr create --base main --head <stacked-1> --title "[1/5] Foundation changes" --body "Stack 1 of PROJECT-123" | grep -oE '[0-9]+$')
PR2=$(gh pr create --base <stacked-1> --head <stacked-2> --title "[2/5] API cleanup" --body "Depends on #$PR1" | grep -oE '[0-9]+$')
PR3=$(gh pr create --base <stacked-2> --head <stacked-3> --title "[3/5] Shared types" --body "Depends on #$PR2" | grep -oE '[0-9]+$')
PR4=$(gh pr create --base <stacked-3> --head <stacked-4> --title "[4/5] Backend flow" --body "Depends on #$PR3" | grep -oE '[0-9]+$')
gh pr create --base <stacked-4> --head <stacked-5> --title "[5/5] Frontend flow" --body "Depends on #$PR4"
Cada gh pr create retorna a URL do PR; grep -oE '[0-9]+$' extrai o número para o próximo Depends on #N.
A lição
Se o trabalho pertence a uma stack, faça uma stack. Idealmente, desde o começo. Se você percebeu tarde demais, peça ajuda para a IA dividir, validar e abrir os PRs.
Top comments (0)