shagghiesuperstar/hermes-skills

Landing em Lote de PRs Apenas de Documentação

Visão Geral

Muitos pull requests pequenos de documentação são mais fáceis de revisar como um só. Este procedimento copia os arquivos de vários pull requests revisados (apenas de documentação) para um novo pull request draft, com um commit por PR fonte. O conteúdo dos arquivos é copiado exatamente, sem edições. Os pull requests fonte não são alterados. Um revisor então mescla o único pull request batch, e os PRs fonte se fecham por seu próprio estado, não através de nenhuma ação neste procedimento.

Quando Usar

• Vários pull requests de documentação abertos passaram pela revisão e cada um toca apenas caminhos de documentação.
• Um revisor solicita um único pull request que carregue todos juntos.

Não use isso para código, configuração, ou para qualquer pull request fonte que não tenha passado pela revisão.

Funcionalidades

• Um worktree temporário, para que o checkout de trabalho não seja tocado.
• Um snapshot ao vivo do estado, base, head e lista de arquivos de cada pull request fonte, verificado contra o commit head buscado.
• Regras para pular pull requests que estão fechados, tocam caminhos fora da pasta de documentação, colidem com main ou colidem com outro pull request aberto.
• Um commit por PR fonte landado, com asserts que interrompem a execução em um PR fonte defeituoso.
• Verificações nos caminhos alterados antes do push e um bloco de verificação que compara o blob de cada arquivo com sua head fonte.

Benefícios

• Um PR fonte defeituoso interrompe a execução ao invés de landar parcialmente.
• O conteúdo de cada arquivo landado é comprovadamente idêntico ao seu conteúdo fonte.
• Pull requests pulados são listados com o motivo, para que nada seja descartado silenciosamente.
• O pull request batch é aberto como draft, para que o revisor tome a decisão final.

Procedimento

1. Trabalhar em um worktree temporário. Busque a branch main e as heads dos pull requests fonte, então crie uma nova branch a partir de main em uma pasta temporária:

   git fetch origin main '+refs/pull/*/head:refs/remotes/origin/pr/*'
   git worktree add -b <batch-branch> <scratch-dir>/wt origin/main
   

   Se um fetch ou push HTTPS falhar na autenticação, execute esse comando com o auxiliar de credenciais definido para a CLI do host de código, por exemplo -c credential.helper= -c 'credential.helper=!gh auth git-credential'. Não altere a configuração armazenada e não imprima um token.

2. Tirar um snapshot do estado uma vez. Para cada pull request fonte, leia seu estado, flag de draft, branch base, commit head e lista de arquivos. Também liste os pull requests abertos para verificações de colisão. Assegure que o commit head de cada PR fonte é igual ao commit buscado em refs/remotes/origin/pr/<n>.

3. Decidir pular ou landar, em ordem numérica. Pule um pull request e registre o motivo se qualquer um dos seguintes for verdadeiro:

   • Não está aberto.
   • Qualquer um de seus caminhos está fora da pasta de documentação.
   • Qualquer um de seus caminhos já existe em main. Para um caminho já em main, compare os blobs. Conteúdo idêntico significa que já foi landado antes. Conteúdo diferente significa que precisa de um rebase.
   • Outro pull request aberto altera qualquer um de seus caminhos.

4. Landar cada pull request como um commit. Para cada pull request landado, faça checkout de seus arquivos a partir do commit head e faça o commit com uma mensagem que nomeie o pull request. Execute isso em um loop que assegura que o PR está aberto, a head corresponde, os caminhos estão sob a pasta de documentação e nenhum deles está em main. Uma asserção falha interrompe a execução.

   git checkout <head-commit> -- <paths>
   git commit -m "docs: land #<n>"
   

5. Verificar as alterações antes do push. O número de arquivos alterados fora da pasta de documentação deve ser zero. O número total de arquivos alterados deve ser igual à soma das contagens de caminhos por pull request.

6. Construir o bloco de verificação. Para cada pull request e cada um de seus caminhos, compare o blob no HEAD da branch batch com o blob na head fonte. Imprima uma linha por pull request, mostrando sua head, contagem de caminhos, contagem de blobs e MATCH, mais um total. Cole o bloco literalmente na descrição do pull request batch.

7. Abrir o pull request batch como draft. Faça push da branch, depois crie o draft contra main. O título indica o número de pull requests realmente landados, não o número considerado:

   gh pr create --draft --base main --title "docs: land <k> reviewed docs PRs" --body-file <body-file>
   

8. Escrever a descrição. Inclua uma nota de que o build foi pulado por ser um diff apenas de documentação, a lista de PRs landados com suas contagens de arquivos e heads, os PRs pulados com seus motivos, quaisquer flags para o revisor e o bloco de verificação. Releia o estado do novo pull request e confirme que é um draft contra main.

Armadilhas

• Ignorar a regra do draft. As instruções de uma execução podem pedir um pull request pronto para revisão. Abra-o como draft a menos que as regras da execução digam o contrário, e indique isso na descrição.
• Um pull request fonte baseado em outra branch. Seus arquivos passam por todas as regras de caminho, mas landá-los em main altera o significado do PR. Inclua-o apenas se as regras permitirem, e sinalize-o com o commit exato a ser descartado.
• Sem merge base. Uma consulta de merge-base pode falhar para tal PR, e um diff contra a base então resulta em erro. Use a lista de arquivos ao vivo como fonte de caminhos. Faça verificação cruzada com um diff contra o merge base apenas onde existir um.
• Um landing parcial. Um pull request que modifica arquivos que main já possui pode ser pulado mesmo que seus outros arquivos sejam novos. Não lande parte dele.
• Inundar a saída com erros de caminho ausente. Uma verificação de que um caminho existe em main imprime um erro para cada caminho ausente. Redirecione o erro padrão para /dev/null nessas verificações.
• Preencher demais o relatório final. Relate a lista de pulados com motivos, as flags e os totais da verificação. Não liste cada arquivo.
• Falta de gráfico ou índice. Se um índice de inteligência de código não estiver disponível para o repositório, indique isso no relatório e não pule as regras de caminho.

Verificação

• O pull request batch é um draft contra main.
• O blob de cada arquivo landado corresponde à sua head fonte, conforme mostrado no bloco de verificação.
• Nenhum arquivo alterado está fora da pasta de documentação.
• Cada pull request pulado tem um motivo na descrição.
• Os pull requests fonte não foram alterados. Este procedimento não mesclou, aprovou, fechou ou comentou neles.