GitHub Stacked PRs

 (github.github.com/gh-stack)
9 pontos por GN⁺ 16 일 전 | 1 comentários | Compartilhar no WhatsApp
  • Novo recurso do GitHub que permite dividir grandes mudanças de código em PRs pequenos e revisáveis para gerenciá-las em sequência
  • Cada PR é revisado de forma independente, e toda a pilha pode ser mesclada com um clique
  • Com a interface do GitHub e a CLI gh stack, há suporte para criar, navegar, rebasear e mesclar pilhas, além de visualizar a hierarquia com o stack map
  • Com a integração de agentes de codificação com IA, é possível dividir automaticamente grandes diffs em pilhas ou desenvolver com base em pilhas
  • O objetivo é reduzir a complexidade e o risco de conflitos em PRs grandes e aumentar a eficiência da revisão e a velocidade de desenvolvimento da equipe

Principais recursos

  • Gerenciamento de PRs em pilha

    • Vários PRs podem ser organizados na forma de uma pilha ordenada (stack), em que cada PR se baseia no branch do PR imediatamente abaixo
    • Isso forma uma estrutura em cadeia que, no fim, chega ao branch principal
    • O GitHub reconhece toda a pilha e exibe um stack map na interface, permitindo que revisores naveguem facilmente por cada camada
    • As regras de proteção de branch se aplicam ao branch de destino final, e os testes de CI são executados para todos os PRs da pilha

  • Gerenciamento simplificado de pilhas

    • Na interface do GitHub, é possível navegar entre os PRs da pilha, verificar o estado de cada camada e executar um cascading rebase em toda a pilha
    • É possível mesclar toda a pilha ou apenas parte dela com um clique
    • Após a mesclagem, os PRs restantes são rebaseados automaticamente, e o PR não mesclado mais abaixo passa a ser ajustado para o branch base

  • Suporte robusto de CLI

    • Com a CLI gh stack, é possível criar pilhas, rebasear, fazer push de branches, criar PRs e navegar entre camadas pelo terminal
    • Exemplos de comandos da CLI
      • gh extension install github/gh-stack : instala a extensão
      • gh stack alias : configura comandos de atalho
      • gs init <branch> : cria o primeiro branch
      • gs add <branch> : adiciona uma nova camada
      • gs push : faz push de todos os branches
      • gs submit : cria os PRs de toda a pilha

  • Integração com agente de IA

    • Com o comando npx skills add github/gh-stack, é possível ensinar um agente de codificação com IA a executar tarefas de pilha
    • Grandes diffs podem ser divididos automaticamente em pilhas, ou o desenvolvimento baseado em pilhas pode ser adotado desde o início

Por que PRs em pilha são necessários

  • PRs grandes causam maior dificuldade de revisão, atraso na mesclagem e risco de conflitos
    • Os revisores perdem o contexto, a qualidade do feedback cai e a velocidade de toda a equipe diminui
  • O Stacked PRs resolve isso ao dividir o trabalho em uma cadeia de PRs pequenos e focados
    • Cada PR pode ser revisado independentemente, enquanto o conjunto completo de mudanças se acumula em sequência

Como começar

Leituras relacionadas

1 comentários

 
GN⁺ 16 일 전
Comentários do Hacker News

  • O que eu preciso não é de "stacked PR", e sim de uma UI para gerenciar commits individuais

    • Quero poder fazer merge só de alguns commits de forma independente, ou marcar um commit específico como revisado
    • Quero fazer interactive rebase/squash/edit no nível de commit, mas isso não é possível na UI do GitHub
    • Preciso de recursos para comentar em mensagens de commit ou em commits específicos, além de visualizar mudanças entre force pushes com diff of diff
      O Git já tem o conceito de commit; não entendo por que colocar outra abstração chamada “stacked PR” por cima disso
    • É um conceito que traz o fluxo de stacked diff criado pelo Phabricator para o GitHub
      Ele facilita começar um novo trabalho em cima de algo que ainda não foi mergeado e permite que revisores façam revisões independentes em partes menores de uma mudança grande
      Era especialmente útil em monorepos grandes ou em ambientes corporativos
    • Mas eu sinto que reescrever o histórico do git o tempo todo é arriscado
      Ficar repetindo squash, rebase e force push parece apontar uma arma para o próprio pé
      git merge --no-ff, git log --first-parent, git bisect --first-parent já conseguem produzir praticamente o mesmo efeito
    • O SuperSmartLog(SSL) que eu usava na Meta foi a melhor implementação
      Está disponível publicamente na documentação do interactive smartlog e também tem extensão para VSCode
      É uma pena que não tenha se espalhado mais
    • O fluxo que eu prefiro é tratar PR/MR como uma “mudança atômica”
      Os commits servem como o processo de evolução para concluir aquele PR
      1. Se o PR ficar grande demais, eu o divido em commits
      2. Registro nos commits o processo de evolução do PR (inclusive motivos como “mudei foo para bar”)
    • O que você descreveu é basicamente Gerrit

  • Depois de usar Phabricator e Mercurial, voltar para o GitHub dá a sensação de voltar para a Idade da Pedra
    Fico feliz em ver o jujutsu e esse novo recurso recriando o fluxo de stacked diff
    Isso ajuda não só em monorepos, mas também no desenvolvimento de funcionalidades de longo prazo, permitindo revisões pequenas e rápidas

    • Ainda bem que o Git venceu a guerra dos DVCS
      O Mercurial sempre dizia que era “mais rápido que o git”, mas na prática era lento ou quebrava
      O Git é feio, mas rápido e confiável
    • Eu ainda odeio a revisão no GitHub, então uso Gerrit
      Ao revisar mudanças grandes (por exemplo, atualização de dependências vendorizadas), a experiência de revisão de arquivos no GitHub deixa a desejar
    • Sinto muita falta da UI de revisão do Phabricator

  • Finalmente saiu!
    O modelo do GitHub de “PR = branch” nunca fez sentido para mim
    O stacked commit no estilo Phabricator/Gerrit combina muito mais com a forma como eu penso
    Agora vou ter que instalar a CLI

    • É uma pena depender da GH CLI, mas espero que até o lançamento geral exista suporte na UI
    • No meu modelo mental, não entendo muito bem a diferença entre branch e stacked PR
      Uma branch é só uma bandeira fincada em um commit, e manter vários pontos só faz sentido quando dá para fazer merge das partes anteriores de forma independente

  • Queria saber se isso resolve o atual problema de UX do Squash & Merge
    Eu empilho manualmente como main <- PR A <- PR B <- PR C,
    e quando o PR A é mergeado primeiro, o PR B vira um inferno de conflitos
    A UI do GitHub muda automaticamente a branch alvo para main e isso gera conflitos estranhos
    Eu só preciso de uma ferramenta que “simplesmente funcione”

    • Os conflitos provavelmente acontecem porque o PR A foi mergeado com squash merge
      Espero que gh stack sync resolva isso com rebase --onto
    • Na prática, isso é tratado com git rebase --onto na CLI e no servidor
      Ex.: PR1(main<-A,B), PR2(main<-A,B,C,D), PR3(main<-A,B,C,D,E,F)
      Se PR1 e PR2 forem mergeados com squash, a main vira S1(A+B), S2(C+D)
      Depois, git rebase --onto S2 D branch3 reorganiza tudo sem conflitos
    • No meu fluxo, se A é mergeado, então B também já deveria estar mergeado
      Dá para resolver com git rebase --update-refs --onto origin/main A C
      A GH CLI automatiza esse processo
    • Esse problema é um limite lógico do git, não um bug
    • Eu também concordo que isso é irritante e nada intuitivo
      Mas, no fim, a solução continua sendo reorganizar os commits manualmente com rebase

  • Quando se desenvolve sozinho, quase não há necessidade de stacked PR, mas o hábito de dividir em unidades pequenas continua importante
    Como ferramentas de IA (ex.: Claude Code) geram diffs grandes de uma vez,
    seria interessante se o agente soubesse dividir o trabalho por conta própria em unidades lógicas

    • Um PR já pode ser composto por vários commits, então, se o agente não consegue navegar bem por isso, com stacked PR será igual
    • Eu uso Claude com jj para que ele reorganize a pilha de trabalho sobre a trunk de forma amigável para revisão
    • Se você faz branches pequenas dependerem umas das outras, entra num inferno de sincronização quando uma branch anterior é atualizada
    • Dá para ver um guia de integração relacionado com agentes na página web

  • Vale a pena conferir o git-spice também
    É compatível com GitLab e outros, e eu uso git-spice para tudo no lugar dos comandos git tradicionais

  • É legal ver o GitHub finalmente colocando uma função de stack na UI
    É parecido com o glab stack do GitLab
    Mas o processo de merge parece um pouco estranho — se você mergear a parte de baixo da pilha, o resto é rebaseado e a CI roda de novo
    Se eu quiser mergear só os dois patches de baixo entre três, vou ter que esperar os testes de cada um

    • Pelo desenho atual, se a CI dos dois PRs de baixo passar, dá para fazer merge de uma vez
      Depois disso, a pilha de cima pode ser rebaseada e a CI talvez rode de novo
      Vamos deixar essa parte mais clara na documentação

  • Não entendo muito bem a necessidade de stacked PR
    No git, já é possível revisar e aplicar conjuntos de patches individualmente
    O modelo de PR, na verdade, acaba juntando tudo em um bloco só
    Stacked PR parece outra abstração para contornar esse problema

    • O time em que trabalhei via o PR em si como a “menor unidade aplicável”
      Os commits internos eram só histórico de desenvolvimento; na hora do merge, tudo era unido em um único commit com squash
      Assim, durante o desenvolvimento você pode empilhar commits livremente, e no merge fica só uma mudança limpa
    • No Phabricator, commit e diff tinham relação 1:1, então parecia muito mais natural
      A implementação do GitHub dá a sensação de ser uma função colada por cima
    • Um PR é, por natureza, uma unidade de mudança atômica, e stacked PR permite trabalhar em cima de um novo PR baseado nele
      Ou seja, é uma estrutura para empilhar o trabalho em etapas, mantendo unidades revisáveis

  • Existe uma startup chamada Graphite já focada em stacked PR
    Eu usava Graphite, então fico feliz em ver o GitHub implementando algo parecido

    • Na empresa onde trabalho também usamos Graphite e estamos satisfeitos

  • Eu gosto de stacked PR, mas essa implementação do GitHub parece feita de um jeito estranho
    Bastaria cada branch apontar para sua branch pai
    Mais do que CLI, o que faz falta é suporte na UI

    • Mas depois que a branch pai é mergeada, o rebase vira um sofrimento
      Seria bom se a CLI automatizasse esse processo
    • A CLI é opcional, e também dá para criar stacked PR pela UI
      A razão para usar uma cadeia de branches é que o diff mostra apenas as mudanças daquela branch
    • Na verdade, isso sempre foi possível no git
      O que faltava era UI e visualização
    • Espero que a próxima etapa traga melhorias na UI