GillMacedo/explaining-go-dependency-bumps

Explicando aumentos de dependências Go

A ferramenta incluída requer Go 1.22 ou mais recente e git para --base. Ela executa go mod graph e go list -m -mod=readonly -json all em cada revisão, com GOWORK=off. Esses comandos leem os arquivos go.mod do módulo e suas dependências; eles não compilam ou executam nenhum código, e não alteram go.mod ou go.sum.

1. Escolha as duas revisões

• Em um pull request, o lado antigo é a base de mesclagem: git merge-base origin/main HEAD. Use o nome do branch apenas se o usuário solicitar.
• --base REF lê os arquivos go.mod e go.sum desse commit com git archive, então as alterações não commitadas na árvore de trabalho são o novo lado. Use --old DIR --new DIR para dois checkouts.
• Execute na raiz do módulo (o diretório com go.mod), ou passe --new MODULE_DIR. Em um repositório com vários módulos, execute uma vez por módulo cujo go.mod mudou.

2. Execute

go run "${CLAUDE_PLUGIN_ROOT}/scripts/whybumped.go" --base "$(git merge-base origin/main HEAD)" --new MODULE_DIR

• Se o pull request informar o que pretendia alterar (um título do Dependabot como "Bump google.golang.org/grpc de 1.63.2 para 1.67.1"), passe com --expect google.golang.org/[email protected]. Então toda outra alteração é um AVISO, incluindo módulos que o go.mod elevou por conta própria.
• Adicione --format json para analisar o resultado.
• As dependências devem estar no cache do módulo ou disponíveis para download pelo proxy do módulo no ambiente. Não altere GOPROXY, GOFLAGS ou GONOSUMDB a menos que o usuário solicite.

Códigos de saída

0 significa nenhum AVISO (ou --fail-on never). 1 significa pelo menos um AVISO. 2 significa que o resultado não é confiável: o go.mod de um dos lados está ausente, vazio, truncado, não é um go.mod ou não tem diretiva go; go mod graph ou go list -m falhou (geralmente uma entrada go.sum ausente, uma versão desconhecida ou sem rede); suas saídas divergem; os dois lados são módulos diferentes; um lado não tem dependências; ou a referência --base não existe. Trate 2 como desconhecido, nunca como aprovado, e mostre o erro ao usuário.

Relatório

1. Comece com go-raised se presente: a linha go antiga e nova, a dependência que precisa da nova versão e como ela entrou no grafo. Se o go.mod foi além do que qualquer dependência precisa, mencione isso.
2. Agrupe as alterações de módulo pela linha "puxado através de": para cada módulo raiz que o go.mod requer, liste o que ele elevou ou adicionou. Estes são os efeitos colaterais dessa atualização.
3. As alterações requested são versões que somente o go.mod solicita. Para um módulo // indirect que foi elevado acima do que qualquer dependência precisa, diga que foi elevado manualmente ou por go get -u, e que poderia permanecer na versão necessária se o usuário quiser uma alteração menor.
4. As alterações lowered e removed informam qual requisitante costumava precisar da versão antiga e para onde esse requisitante foi. Um módulo abaixado é um downgrade no build; mencione claramente.
5. requirement-dropped significa que o go.mod perdeu uma linha enquanto o build manteve a mesma versão através de outro módulo. go mod tidy faz isso quando nenhum pacote precisa do módulo. Se o usuário não executou tidy, verifique se o go.mod não foi danificado.
6. Uma cadeia através de uma versão que não é selecionada é real: na seleção de versão mínima, as exigências de todas as versões no grafo contam, mesmo aquelas que perderam para uma versão mais nova.
7. Não edite o go.mod a menos que o usuário solicite. Se ele quiser uma alteração menor, a correção usual é go get module@version apenas para o módulo raiz, depois go mod tidy, e execute a ferramenta novamente.