GillMacedo/explaining-go-dependency-bumps

Erklärung von Go-Abhängigkeitserhöhungen

Das gebündelte Tool benötigt Go 1.22 oder neuer und git für --base. Es führt go mod graph und go list -m -mod=readonly -json all auf jeder Revision aus, mit GOWORK=off. Diese lesen die go.mod-Dateien des Moduls und seiner Abhängigkeiten; sie bauen oder führen keinen Code aus und ändern weder go.mod noch go.sum.

1. Wähle die zwei Revisionen

• In einem Pull-Request ist die alte Seite die Merge-Basis: git merge-base origin/main HEAD. Verwende nur den Branchnamen, wenn der Benutzer danach fragt.
• --base REF liest go.mod- und go.sum-Dateien dieses Commits mit git archive, sodass nicht-committete Änderungen im Arbeitsbaum die neue Seite sind. Verwende --old VERZ --new VERZ für zwei Checkouts.
• Führe es im Modul-Root (dem Verzeichnis mit go.mod) aus, oder übergib --new MODUL_VERZ. In einem Repository mit mehreren Modulen führe es einmal pro Modul aus, dessen go.mod sich geändert hat.

2. Führe es aus

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

• Wenn der Pull-Request angibt, was geändert werden sollte (ein Dependabot-Titel wie "Bump google.golang.org/grpc from 1.63.2 to 1.67.1"), übergib es mit --expect google.golang.org/[email protected]. Dann ist jede andere Änderung eine WARN, einschließlich Module, die go.mod von selbst erhöht hat.
• Füge --format json hinzu, um das Ergebnis zu parsen.
• Abhängigkeiten müssen im Modul-Cache oder über den Modul-Proxy in der Umgebung herunterladbar sein. Ändere GOPROXY, GOFLAGS oder GONOSUMDB nur, wenn der Benutzer danach fragt.

Exit-Codes

0 bedeutet keine WARN (oder --fail-on never). 1 bedeutet mindestens eine WARN. 2 bedeutet, dass das Ergebnis nicht vertrauenswürdig ist: die go.mod einer Seite fehlt, ist leer, abgeschnitten, keine go.mod oder hat keine go-Direktive; go mod graph oder go list -m ist fehlgeschlagen (oft ein fehlender go.sum-Eintrag, eine unbekannte Version oder kein Netzwerk); ihre Ausgaben stimmen nicht überein; die beiden Seiten sind unterschiedliche Module; eine Seite hat überhaupt keine Abhängigkeiten; oder der --base-Ref existiert nicht. Behandle 2 als unbekannt, niemals als Bestehen, und zeige dem Benutzer den Fehler.

Bericht

1. Beginne mit go-raised, falls vorhanden: die alte und neue go-Zeile, die Abhängigkeit, die die neue Version benötigt, und wie sie in den Graphen gelangt ist. Wenn go.mod weiter gegangen ist, als jede Abhängigkeit benötigt, sage das.
2. Gruppiere die Moduländerungen nach der "pulled in through"-Zeile: für jedes Root-Modul, das go.mod benötigt, liste auf, was es erhöht oder hinzugefügt hat. Dies sind die Nebeneffekte dieses Upgrades.
3. requested-Änderungen sind Versionen, die nur go.mod verlangt. Für ein // indirect-Modul, das über das hinaus erhöht wurde, was jede Abhängigkeit benötigt, sage, dass es von Hand oder durch go get -u erhöht wurde, und dass es auf der benötigten Version bleiben könnte, wenn der Benutzer eine kleinere Änderung wünscht.
4. lowered- und removed-Änderungen sagen, welcher Anforderer früher die alte Version benötigte und wohin dieser Anforderer gegangen ist. Ein gesenktes Modul ist ein Downgrade im Build; erwähne es klar.
5. requirement-dropped bedeutet, dass go.mod eine Zeile verloren hat, während der Build die gleiche Version über ein anderes Modul behalten hat. go mod tidy macht dies, wenn kein Paket das Modul benötigt. Wenn der Benutzer tidy nicht ausgeführt hat, überprüfe, ob go.mod nicht beschädigt ist.
6. Eine Kette durch eine Version, die nicht ausgewählt ist, ist real: bei der minimalen Versionsauswahl zählen die Anforderungen jeder Version im Graphen, auch die, die gegen eine neuere Version verloren haben.
7. Bearbeite go.mod nicht, es sei denn, der Benutzer fragt danach. Wenn sie eine kleinere Änderung wünschen, ist die übliche Lösung go get modul@version nur für das Root-Modul, dann go mod tidy, und führe das Tool erneut aus.